feat(agent-toolkit): agents subgraph tools expansion

[NadavAvraham]

monday item

https://monday.monday.com/boards/10045819454/pulses/10045820228

Summary

• Adds 6 new tools to @mondaydotcomorg/agent-toolkit covering the full agents subgraph surface
• get_agent_catalog — discovers available trigger types and skills account-wide (READ)
• manage_agent_triggers — list, add, and remove triggers on an agent (WRITE)
• manage_agent_skills — create custom skills, attach and detach skills from an agent (WRITE)
• update_agent — update an agent's name, role, description, or execution plan (WRITE)
• manage_agent_state — activate, deactivate, or manually run an agent (WRITE)
• manage_agent_knowledge — list, grant, update, and revoke an agent's access to boards and docs (WRITE)
• Bumps package version to 5.11.0

Design decisions

• Tool descriptions encode catalog-first workflows so agents know to call get_agent_catalog before adding triggers or skills
• manage_agent_triggers and manage_agent_knowledge include a list action to support the lookup-before-mutate pattern (get node_id / inspect current state before remove/update)
• All tools use versionOverride: 'dev' — the agents subgraph is still on the dev API version
• manage_agent_skills consolidates skill creation (create_agent_skill mutation) alongside attach/detach in one tool since they're all skill management operations
• GraphQL operations are co-located with each tool's directory rather than centralised in shared/

Test plan

• npm test passes (1013 tests across 55 suites)
• npm run build compiles cleanly
• Each tool has happy-path, validation-error, null-response, and API-error-propagation coverage

🤖 Generated with Claude Code

[RanEldann]

Strong addition overall — the 6 new tools follow established patterns in the toolkit, tests cover happy paths plus most error/null/validation cases, and the GraphQL operations are correctly wired. Auth model is fine: JWT-scoped, every mutation goes through authorizeAgentAction('edit', agentId), no security concerns from the toolkit perspective.

Three blocking issues

1. Prettier will fail CI — create-agent-tool.ts:166-171 has an 8-space indent in a 6-space block. Looks like an editor mishap during the latest edits.
2. .optional() + manual throw instead of z.discriminatedUnion across all four manage_* tools. The repo already uses discriminated unions in 4 places (update-doc-tool.schema.ts, create-doc-tool.ts). The current pattern means LLMs see all action-conditional fields as optional in the JSON schema and only learn requirements via runtime errors.
3. field_values: z.record(z.unknown()) in manage_agent_triggers provides no schema guidance to the LLM. The description tells it to call get_agent_catalog and follow field_schemas, but the JSON schema is fully untyped — three different shape conventions hide behind one record.

Theme: description ↔ code drift

Several tool descriptions claim or imply behaviors the code doesn't deliver:

• inactive_reason's "omit if ambiguous" is meaningless because the code defaults to the same value either way (it's also a 1-value enum, so the field is pure noise)
• update_agent's "profile or execution plan" overpromises — avatar_url, background_color, goal, user_prompt aren't in UpdateAgentInput
• agent_model's "degrades the agent's performance" is wrong — invalid values are rejected by the server, not degraded
• manage_agent_triggers doesn't mention that the catalog excludes 3rd-party (OAuth) triggers — LLMs will look up Slack/Salesforce and be confused they're missing
• manage_agent_knowledge's "call list first" is overstated — only needed for update/remove, not add

Theme: cross-tool inconsistency

• update_agent returns { content: agent } while siblings return { content: { message, agent } } — LLM has to learn per-tool shapes
• agent_id (new tools) vs id (existing update/get/delete-agent) — same concept, two names
• count field on most list responses but missing from knowledge list

Nits

• Missing CHANGELOG.md entry for 5.11.0 (the agent-toolkit/CLAUDE.md mandates this — though to be fair, CHANGELOG was already stale at 5.7.1)
• update-agent-tool.test.ts has 3 expect()s in a single it() — violates the "one assert per test" rule used elsewhere
• rethrowWithContext strings are verbose and inconsistent — 4 of them have double-"agent" ("list agent knowledge for monday platform agent", etc.). The "monday platform agent" suffix is wasted tokens in every error
• Domain validation errors (e.g. throw new Error('create_agent_skill returned no data')) get double-wrapped to "Failed to X: <inner>" because the throw is inside the try block
• trigger_uuid returned by manage_agent_state action:run has no companion query yet — the description should say "store for future correlation; no run-status query exists yet"
• manage_agent_knowledge list returns a files array the tool can't act on; the description has to apologize. Either drop from the GraphQL selection or split into a separate read tool

Recommendations

1. Fix Prettier first (item 1) — that's CI.
2. Convert the four manage_* schemas to z.discriminatedUnion('action', [...]). This single change fixes findings 2, 4, 8, 13, plus removes the manual cross-field throws.
3. Fix the description honesty issues (medium-severity but cheap) — they directly affect tool-call success rate in production.
4. Align update_agent's return shape and rename id → agent_id for consistency.
5. Optional but recommended: type agent_model as z.nativeEnum(AgentModel) so wrong values fail at zod time with a clear list of valid options, instead of producing a confusing GraphQL error.

Nice work overall — happy to clarify or drop any of the smaller items.

[RanEldann]

Nadav 👑 you're a king. Genuinely impressive turnaround — almost every finding addressed, several solved structurally (extracting create_agent_skill, dropping inactive_reason entirely), and descriptions are now honest about what each tool actually does. This is a major enhancement — agents can now manage the full agent lifecycle end-to-end with schemas they can actually act on. Approving 🎉

One thought on the discriminated-union pushback before we move on — I think the blocker is smaller than it looked, and the LLM ergonomics win is real:

The actual constraint is just Input extends ZodRawShape in BaseMondayApiTool plus 3–4 z.object(inputSchema) sites in toolkit.ts. ~15 lines, fully backwards-compatible:

// base-monday-api-tool.ts
export type ToolInputSchema = ZodRawShape | ZodTypeAny | undefined;

export abstract class BaseMondayApiTool<
  Input extends ToolInputSchema,
  Output extends Record<string, unknown> = never,
>

// toolkit.ts — small helper
function buildZodSchema(input: any): ZodTypeAny | undefined {
  if (!input) return undefined;
  if (typeof input.safeParse === 'function') return input;  // already a Zod schema
  return z.object(input);  // ZodRawShape — existing tools
}
// then replace the 4 z.object(inputSchema) sites with buildZodSchema(inputSchema)

Then each manage_* schema becomes z.discriminatedUnion('action', [...]) with one z.object per variant. zodToJsonSchema produces oneOf with per-action required arrays — the LLM sees "for action=add, resource_id + scope_type + permission_type are required" in the schema itself instead of parsing it out of prose.

LLMs miss conditional prose ("Required for action:X") reasonably often. Discriminated oneOf cuts misuse-on-first-try meaningfully on real workloads. Bonus: drops the manual if (!input.x) throw blocks and TypeScript narrows the input type per case branch in executeInternal.

Fully backwards-compatible — every existing ZodRawShape tool keeps working unchanged. Not blocking, just smaller than the "follow-up" reply implied. Up to you whether to do it here or a separate PR 🙂

Great work 🚀