n8n_manage_agents

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful behavioral context beyond annotations: it discloses the need for N8N_MCP_ACCESS_TOKEN and n8n version requirements, explains that call runs 'with real credentials and tools,' warns about approvals, and clarifies that projectId defaults to the personal project. Annotations already signal destructive and non-read-only behavior, and the description enriches that with operational caveats, though individual destructive actions like delete or revert are not deeply detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but each sentence contributes: scope, prerequisites, action list, recommended sequence, projectId behavior, publication safety caveat, call side-effect warning, and sibling differentiation. It could be improved with clearer separation of the long action list, but it is not padded or redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 15 actions and no output schema, the description provides a strong operating context: how to start, what to do at each stage, key behaviors, and where to find per-action details via tools_documentation. It does not fully document every action's side effects, but it points to the full reference and covers the most safety-critical aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is already strong. The description adds value by explaining that args are 'forwarded to n8n unchanged' except for projectId substitution, and by giving guidance like 'always with the latest configHash.' The timeoutMs parameter is also given contextual meaning with the special default for action=call. This goes beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Manage n8n Agents (persisted assistants...)' and enumerates a concrete set of actions. It explicitly distinguishes itself from siblings by noting 'This is not the AI Agent workflow node; use get_node for that.' This gives an agent a clear, unambiguous picture of what the tool operates on and what it is not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit recommended workflow: 'Start with action=reference... then discover_assets → create → mutate... → validate.' It also gives guardrails: 'publish only when the user explicitly asks' and warns that call 'may return approvals[]' and to 'never approve on the user's behalf.' These are concrete when-to-use and when-not-to-use instructions, far beyond a generic hint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.