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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds behavioral context: "makes exactly one POST /audit request," "safe to retry but remains unsafe-mode and owner-authorized," and "Returns a sanitized, untrusted report; a clean scan returns an empty map." This enriches the agent's understanding of security, side effects, and failure behavior.

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?

Despite being relatively long, every sentence adds value: purpose, parameter usage, side effects, safety, alternatives, return behavior, and retry guidance. It is front-loaded with the main purpose and maintains a clear logical flow. No filler or redundancy.

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?

Given the tool's simplicity (one optional parameter) and the rich annotations plus an output schema, the description goes beyond what is necessary by covering authorization, sensitivity, return format, and failure mitigation. It is fully complete for an agent to invoke correctly.

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?

The schema already fully describes the categories parameter (1-5 unique items, optional, default selection). The description adds one important constraint beyond the schema: "an empty array is rejected." This is a meaningful behavioral detail, but most parameter semantics are already in the schema, so the description's incremental value is limited to that rejection rule.

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 opens with a specific verb and resource: "Run one read-only n8n security scan." It clearly distinguishes itself from siblings by mentioning an alternative for single-workflow inspection ("Use n8n_introspect for one workflow"). This makes the purpose unambiguous and differentiated.

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?

Provides explicit usage context: when to omit categories for a default scan, accepts 1-5 categories, and rejects empty arrays. It also names an alternative tool (n8n_introspect) for a different use case and gives retry advice if the report cannot fit, which serves as clear when-to-use and troubleshooting guidance.

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

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

The description adds significant context beyond annotations: it mentions the 100-record cap, exact omission reporting, the package-list permission requirement, and that metadata is untrusted with emails redacted. These are substantive behavioral traits not present in the readOnly/idempotent hints.

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?

Three dense sentences, each carrying distinct value: purpose, limits/omissions, alternative, permissions, and safety. No wasted words; information is front-loaded.

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 simple zero-parameter tool with a rich annotation set and output schema, this description covers all necessary context: scope, limits, permission, trust level, and relationship to siblings. Nothing essential is missing.

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?

Though the schema has zero parameters, the description explicitly states 'accepts no arguments, filters, cursor, or limit.' This prevents the agent from assuming pagination or filtering capabilities and fully clarifies parameter semantics.

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 opens with a specific verb and resource: 'List bounded metadata for installed n8n community packages.' It also explicitly differentiates from a sibling tool by directing users to n8n_list_node_types for workflow type observation, making its scope unmistakable.

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?

It provides an explicit alternative ('Use n8n_list_node_types for types observed in workflows') and clearly states non-behaviors ('does not download or inspect contents', 'never installs, updates, or removes packages'). This helps the agent decide when to choose this tool over others.

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

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

The description adds meaningful behavior beyond annotations: it explains that secrets belong only in the data input, are excluded from logs/output, and that the tool returns metadata only. It also clarifies that isResolvable is forwarded only when supplied, giving the agent concrete operational expectations beyond the readOnly/write flags.

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 three dense sentences, each earning its place. It front-loads the core purpose, then layers preconditions, guidance, and security behavior without fluff. It is appropriately sized for the tool's complexity.

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?

Given the tool's complexity and the presence of an output schema, the description covers all essential context: prerequisite schema lookup, required mode/permission, secret handling, response shape, and how to handle existing credentials. No significant gaps remain.

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?

Even though schema coverage is 100%, the description adds semantic depth: it clarifies that 'name is only the stored label,' that isResolvable is forwarded only when supplied, and that data values are never returned. These insights go beyond the raw schema descriptions, helping the agent construct correct requests.

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 opens with 'Create and persist one credential as an additive write,' which identifies the specific verb, resource, and additive nature. It also explicitly distinguishes itself from the update sibling by naming n8n_credentials_update for existing credentials, clarifying its unique scope.

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?

Provides clear sequencing guidance: first call n8n_credentials_schema with the planned type, then build data from its field contract. It explicitly directs users to n8n_credentials_update for existing credentials and states the required mode/permission, offering both when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (destructiveHint=true), the description discloses that deletion 'can break every referencing workflow,' that no secret or rollback is returned, and that it requires 'unsafe mode plus credential-delete permission.' It also describes the return value. This adds significant behavioral context beyond what annotations alone provide.

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 three dense sentences, front-loaded with the core action and consequence. Every sentence provides necessary information—side effects, ID requirements, prerequisites, and return behavior—with no filler or repetition.

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?

Despite the tool's simplicity (one parameter), the description covers the essential context: side effects, parameter identification, prerequisites, permissions, and return value. An output schema exists, and the description still adds value by explaining the request-bound response. It is fully complete for an agent to safely invoke this destructive operation.

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 3. The description adds crucial semantics by specifying that credentialId 'must be the stable ID from n8n_credentials_list, get, or create; a credential name or type is not accepted.' This goes beyond the schema's 'Stable ID' description and clarifies valid sources and invalid alternatives.

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 clearly states 'Permanently delete one stored credential' – a specific verb and resource with the permanent and singular scope. It distinguishes this from sibling tools like n8n_credentials_update and n8n_credentials_test by focusing on deletion and its irreversible nature.

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 explicitly advises to 'Scan all n8n_credentials_usage pages first, or update when replacement is enough,' giving clear guidance on prerequisites and when to prefer the update tool. It also notes the permission requirement, providing a complete usage context.

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

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

While annotations already mark the tool as read-only, idempotent, and non-destructive, the description adds valuable behavioral context: it requires credential-read permission, returns only validated identity/type/flags/timestamps, and does not retrieve secret data or test the service. This goes beyond the annotations and fully informs the agent about side effects and limitations. No contradiction exists.

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 four concise sentences with no fluff. It front-loads the core purpose, then adds important constraints, permissions, return contents, and alternatives. Every sentence earns its place and the structure is logically ordered.

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 single-parameter read tool with rich annotations and an output schema, the description covers all necessary context: purpose, parameter source, permissions, return summary, exclusions, and a pointer to a sibling tool. It is complete for an agent to correctly select and invoke the tool without further clarification.

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?

Although the schema already describes credentialId as a stable ID, the description enriches this significantly: it clarifies that the ID is from n8n_credentials_list or create, and crucially that it is not the name, type, or secret data. This disambiguation prevents misuse of the parameter and adds meaning well beyond the schema description.

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 starts with 'Get public metadata for one stored credential'—a specific verb+resource. It clearly distinguishes from siblings by stating it does not retrieve credential values or test the external service, and points to n8n_credentials_schema for type fields. This makes the tool's purpose unmistakable and differentiates it from list, schema, test, and update tools.

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 explicitly tells when to use this tool: when you need public metadata for a single stored credential. It directs users to n8n_credentials_schema for type fields, explains that credentialId comes from n8n_credentials_list or create, and clarifies what the endpoint does not do (retrieve values or test). This gives clear guidance on selecting this tool over alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description discloses that the tool never auto-paginates, returns only metadata and nextCursor (never stored values), and requires a specific permission. These are meaningful operational behaviors not captured in the annotations, significantly enhancing transparency.

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 four sentences, each covering a distinct aspect: purpose, pagination instructions, alternative tool, and permission/results. It is front-loaded with the primary action and every sentence earns its place without redundancy.

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?

Given the tool's simplicity and the presence of an output schema, the description covers version compatibility, pagination behavior, permission requirements, and return value restrictions. It also names the alternative tool for specific cases. No obvious gaps remain for an agent to select and invoke this tool correctly.

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?

The schema already documents both parameters with 100% coverage. The description adds operational nuance: the cursor should be 'passed back unchanged' from nextCursor, and limit applies only to that request. This goes beyond the schema's basic descriptions, adding real value for correct usage.

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 opens with a specific verb and object: 'List one Public API page of credential metadata.' This clearly identifies the resource (credentials metadata) and scope (single page). It also distinguishes from sibling n8n_credentials_get by stating 'Use n8n_credentials_get when an ID is known.'

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 explicitly directs the agent to n8n_credentials_get when an ID is known, provides pagination usage rules (omit cursor for first page, pass nextCursor back unchanged), and clarifies that limit applies per request only. It also mentions the required permission ('credential-list permission'), giving clear context for when this tool is appropriate.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral context: it returns a 'validated upstream field contract,' does not touch stored credentials, and requires specific permissions. This helps the agent understand side effects and expectations.

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 concise and well-structured: it starts with the core purpose, then clarifies key terminology, states limitations, and points to an alternative. Every sentence adds distinct value without redundancy.

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?

Given the simple single-parameter contract and existing output schema, the description is complete. It covers purpose, parameter semantics, usage alternatives, prerequisites, and behavioral constraints, leaving no critical gaps for an agent to invoke the tool correctly.

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?

While the schema covers the format of credentialType, the description adds crucial semantic meaning: it clarifies that credentialType is the 'public type name used by create/update, not a stored credential ID, name, or secret.' This prevents common misuse and goes beyond schema-level documentation.

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 clearly states the tool's function: 'Get n8n's Public API field contract for one credential type.' It uses a specific verb and resource, and explicitly distinguishes itself from n8n_credentials_get by noting the difference between public type names and stored credential metadata.

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 explicitly tells when to use this tool versus alternatives: 'Use n8n_credentials_get for stored metadata.' It also clarifies what it does not do ('does not read or test a stored credential') and mentions the required 'schema-read permission,' providing clear usage boundaries.

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

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

The description discloses key behavioral traits beyond annotations: the tool contacts an external service, may log the attempt, returns only the target-bound OK/Error outcome, and withholds the upstream diagnostic message. This complements the annotations without contradiction.

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 compact and every sentence earns its place. It covers purpose, parameter source, usage guidance, permissions, and output behavior in four sentences with no redundancy.

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?

Given the simple single parameter, rich annotations, and presence of an output schema, the description is complete. It provides all necessary context for an agent to select and invoke the tool correctly, including side effects and safety considerations.

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?

The schema covers the credentialId parameter, but the description adds important semantic detail: it specifies the ID comes from credentials_list or get, and explicitly states that inline credential data, names, and types are not accepted. This goes beyond the schema's simple description.

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 clearly states the tool's purpose: testing an already stored credential by contacting its external service. It distinguishes itself from related tools like get (metadata-only) and list by specifying that inline credential data is not accepted and that it targets stored credentials.

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?

Explicit guidance is provided: 'Use get for metadata-only inspection and skip this tool when network contact is unwanted.' It also notes the requirement for unsafe mode and test permission, giving clear conditions for when this tool is appropriate.

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

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

Discloses significant behavioral traits: 'potentially breaking dependent workflows' warns of destructive impact, and 'isPartialData=false replaces the saved field set, while true requests a partial merge' explains update semantics. Also notes 'returns metadata without secret values,' informing about output privacy. These align with destructiveHint=true and readOnlyHint=false annotations.

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?

Four dense sentences pack all key information—purpose, risk, selection, partial semantics, type change, alternative, permissions, and return behavior—without redundancy. Semicolons effectively group related clauses.

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?

The description covers the tool's destructive potential, update semantics, permissions, secret handling, and the creation alternative. With an output schema present, not detailing return fields is acceptable; all essential usage aspects are addressed.

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?

Even with 100% schema coverage, the description adds meaning: it clarifies that credentialId selects the record, fields can be omitted to keep current values, type changes require data matching n8n_credentials_schema, and isPartialData toggles replace vs. merge. This goes beyond the schema's per-field descriptions.

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?

Description opens with 'Update one stored credential,' specifying verb and resource. It differentiates from create by noting 'Use create for a new credential,' and from other credential tools by focusing on the update action.

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?

Clear context: targets an existing credential selected by credentialId, with explicit alternative 'Use create for a new credential' preventing confusion with creation. Prerequisites (write/unsafe mode + update permission) and partial-update guidance help the agent decide when to invoke.

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

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

Beyond the readOnly/idempotent annotations, the description reveals important behaviors: unresolved legacy references are 'counted but never matched,' coverage completeness depends on nextCursor, and the response is bounded with omission counts. It also discloses permission requirements. No contradiction with annotations.

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 concise (~70 words) and front-loaded: it states the core purpose first, then packs pagination, legacy behavior, usage context, permission, and result shape into a tight paragraph. Every sentence adds value with no redundancy.

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?

Given the tool's pagination complexity, permission requirements, and legacy-reference edge case, the description covers all essential operational aspects. It explains how to paginate, when coverage is complete, what counts as unmatched, and the expected output nature ('bounded workflow/node matches and omission counts'), while the output schema handles return structure details.

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?

The schema already covers all parameters (100% coverage), but the description adds critical context: credentialId is described as the stable ID from n8n_credentials_list or get, and pagination semantics are clarified (omit cursor for first page, keep other params stable with nextCursor). This goes beyond the schema's basic descriptions.

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 opens with a specific verb+resource: 'Scan one workflow page for exact references to a credential.' It clearly distinguishes from siblings by targeting credential usage, and explicitly ties it to pre-update/delete checks (e.g., 'Use this before update/delete'), setting it apart from credential CRUD and workflow search tools.

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?

Provides direct usage guidance: 'Omit cursor for page one; keep credentialId, active, and limit unchanged when passing nextCursor' and 'Use this before update/delete.' It also states a prerequisite permission ('Requires workflow-list permission') and explains when coverage is complete ('only when nextCursor is null'). This is explicit, actionable guidance.

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

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

Beyond the annotations' destructiveHint, the description adds crucial behavioral context: the deletion is permanent, retained history is also deleted, there is no recovery/rollback, unsafe mode plus execution-delete permission are required, and the response includes the request-bound executionId with deleted=true.

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 three focused sentences, each serving a purpose: what it does, what input is valid, and what to expect/prepare for. It is front-loaded with the core action and avoids redundancy.

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 single-parameter destructive tool with a clear output schema and annotations, the description is complete. It covers purpose, ID source/constraint, preflight verification, permission requirements, irreversibility, and return behavior.

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?

The schema already fully covers the executionId type and pattern. The description adds important semantic value by clarifying that the ID must be a saved execution record ID from list/get and that workflow IDs are not accepted, which helps prevent misuse.

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 opens with a specific verb and resource: 'Permanently delete one saved execution and its retained history.' It clearly distinguishes itself from sibling tools by stating that the executionId must come from n8n_executions_list or get, not a workflow ID.

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?

It provides explicit guidance: the executionId must be a saved execution record ID, not a workflow ID, and advises confirming the target with get before deleting. This directly tells the agent when and how to use the tool safely.

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

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

Beyond annotations, reveals that includeData triggers a request to n8n but the MCP still withholds all payload data, and specifies the returned fields (identity, status, timing, retry, dataPolicy). Adds meaningful behavioral context.

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?

Three dense sentences, front-loaded with the action, and no filler. Every clause adds value.

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?

Complete for a simple 2-param read tool: purpose, permission, ID semantics, return shape, and data access limitations are all covered. Output schema exists and is not contradicted.

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?

Even with 100% schema coverage, the description clarifies that executionId is the list-based record ID (not workflowId) and explains the true behavior of includeData, which the schema only partially captures. Adds significant meaning.

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?

States clearly it gets metadata for a single execution, and explicitly distinguishes executionId from workflowId. Differentiates from the list sibling by saying 'Use list for discovery.' Verb+resource is precise.

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?

Gives explicit alternative ('Use list for discovery') and notes the permission requirement. Also implies when not to use (for payload data) by explaining includeData still withholds node inputs/outputs.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses crucial behavior: 'never auto-paginates,' 'includeData only reports whether data exists—values remain withheld,' and 'returns metadata and nextCursor.' This adds meaningful context about pagination limits and data privacy that annotations alone do not convey.

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?

Three sentences, each with a distinct purpose: purpose/scope, usage guidance, and behavioral/security constraints. No redundant or filler words; the description is dense yet readable and front-loaded with the most important info.

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?

The tool has an output schema, so return values are documented there. The description covers permission requirements, pagination behavior, and the nuance that data values are withheld even when includeData is true. Given the tool's simplicity and strong annotations/schema coverage, this description fully equips an agent to use it correctly.

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?

Although the schema already provides 100% parameter descriptions, the description adds semantic depth: 'status and workflowId filter upstream' clarifies server-side filtering, 'cursor resumes one prior page' explains the cursor's single-step behavior, and 'includeData only reports whether data exists' explicitly resolves the parameter's meaning beyond its schema text. This is valuable added meaning.

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 opens with a specific verb and resource: 'List one Public API page of saved execution metadata.' It clearly distinguishes the tool from its sibling by noting 'use n8n_executions_get when an ID is known,' which positions this as the discovery/triage tool.

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?

Explicit guidance is given: 'Use it for discovery and bounded triage; use n8n_executions_get when an ID is known.' It also states the required permission ('Requires execution-list permission') and pagination behavior ('never auto-paginates'), leaving no ambiguity about when and how to use it.

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

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

The description adds key behavioral context beyond annotations: side effects ('A retry may repeat earlier external effects'), loadWorkflow semantics, and return shape ('returns metadata without payload values'). This complements the annotation hints (destructiveHint=true, idempotentHint=false) without contradiction.

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 three sentences, tightly packed with essential information, front-loaded with the core purpose. No redundant phrases; every sentence adds value.

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?

Given the tool's complexity (mutation with side effects, permissions, alternatives, return type), the description covers all critical aspects: retryability conditions, data source, loadWorkflow behavior, external effects, alternative tool, and permission requirements. Output schema exists, so return-value details are not needed.

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?

Even though schema coverage is 100%, the description adds meaning for both parameters: it clarifies executionId provenance (from get/list) and explains the loadWorkflow distinction ('true uses the currently saved workflow, while false uses the original execution snapshot'), which goes beyond the schema descriptions.

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 opens with 'Retry one saved execution that has retry data and did not finish successfully', using a specific verb and resource, and clearly delineates the tool's scope from siblings like delete, stop, get, and list. This distinguishes it effectively.

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?

Explicitly states when retry is rejected ('n8n rejects queued/new executions and successful finished executions'), gives the source for executionId ('comes from n8n_executions_get or list'), points to an alternative tool ('use stop for a running execution'), and lists prerequisites ('requires unsafe mode and retry permission'). This is comprehensive guidance.

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

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

Beyond the destructiveHint annotation, the description discloses that HTTP 200 alone does not prove cancellation, explains response-state mapping, notes that completed external effects remain, and states required permissions. This adds significant behavioral context that annotations alone do not provide.

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 every sentence provides necessary operational details. It is front-loaded with the core purpose and then layers constraints and caveats. Slightly longer than strictly necessary, but no waste.

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 destructive mutation tool with a single parameter, the description covers prerequisites, error conditions, response interpretation, and side effects. The output schema already documents return values, so the description completes the behavioral contract effectively.

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%, but the description adds crucial meaning by clarifying that executionId is the record ID from list/get, not a workflow ID, and reinforces the accepted types. This goes beyond the schema's generic 'stable execution ID' and prevents a common misuse.

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 uses a specific verb ('Request cancellation') and a clear resource ('one stoppable execution') with explicit statuses (new, unknown, waiting, or running). It also distinguishes the tool from sibling execution tools by focusing on cancellation rather than deletion, listing, or retrying.

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?

Provides clear usage guidance: executionId must come from n8n_executions_list or get, not a workflow ID, and executions already terminal are rejected. It states prerequisites (unsafe mode and stop permission) and implies the tool is for non-terminal executions. However, it does not explicitly name an alternative for other operations, leaving a slight gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond annotations: it is 'immutable,' 'never follows the included URL,' and requires 'no n8n URL, API key, network, or elevated mode.' It also discloses the return payload structure (source/fetched provenance, canonical type, title, summary, guidance, official URL), which enriches the behavioral contract without contradicting annotations.

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?

Two sentences deliver high-density information without waste. The first sentence states the purpose and the exact accepted keys; the second sentence covers alternatives, prerequisites, side-effect behavior, and the precise return fields. Each clause earns its place, and the most critical info is front-loaded.

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?

Given the tool's simplicity (one parameter, enum, output schema present), the description is complete: it covers the parameter's exact semantics, the absence of network/authentication needs, side-effect-free behavior (never follows URL), and what will be returned. No crucial information is missing for an agent to invoke it correctly.

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% and the enum already limits node to four valid values. The description adds value by clarifying that 'node is an exact local key—webhook, code, http-request, or if—not an arbitrary n8n node-type string,' which prevents common misinterpretations and explains the semantic distinction vs. generic node types. This goes beyond a simple restatement of the 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 opens with 'Return one immutable bundled reference,' clearly identifying the verb (return), resource (node documentation), and scope (immutable bundled reference). It distinguishes from siblings by explicitly directing users to n8n_list_node_types for inventorying types and official docs for anything else, making the tool's unique purpose unambiguous.

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 gives explicit when-to-use guidance: 'node is an exact local key—webhook, code, http-request, or if—not an arbitrary n8n node-type string.' It also states exclusions ('not an arbitrary n8n node-type string') and names alternatives (n8n_list_node_types, official docs), fulfilling both positive and negative usage criteria.

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

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

Beyond annotations, the description discloses specific behaviors: one redirect-free request, 10-second timeout, no arguments, auth requirements, environment variable for insecure HTTP, no workflow data read/changed, and that only ok=true and status are returned, never the body. This adds substantial value over annotations.

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 concise but thorough, with each sentence serving a distinct purpose: behavior, prerequisites, usage guidance, side-effect safety, and return value. It is well-structured and front-loaded with the core action.

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?

Given the tool's simplicity and the presence of an output schema, the description fully covers what the agent needs: request behavior, prerequisites, usage separation, and return specifics. There is no missing information for a health-check tool.

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?

The tool has zero parameters, so schema coverage is complete. The description explicitly states 'accepts no arguments', which adds clarity and reinforces the schema. Baseline for 0 params is 4, and this is met.

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 clearly states the tool performs a redirect-free same-origin /healthz request with a 10-second timeout, which is a specific verb+resource. It also distinguishes itself from siblings by explicitly directing to n8n_workflows_list for API-key capability testing.

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?

Provides explicit usage context: use for HTTP reachability, then use n8n_workflows_list for API-key capability. It also notes prerequisites (configured URL, API key, N8N_ALLOW_INSECURE_HTTP for plaintext) and states what is not read or changed.

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

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

Annotations already declare read-only, idempotent, and non-destructive hints, and the description adds valuable context: requires 'insights-read permission', 'never fabricates unavailable metrics', and enumerates the return aggregates (totals, failures, rates, time saved, runtime). It also notes the inclusive offset-aware bounds, which goes beyond the schema.

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 concise yet information-dense, with each sentence serving a distinct purpose: purpose, usage guidance, parameter semantics, and behavioral/permission details. It is front-loaded with the core purpose and contains no redundant filler.

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?

Given the availability of an output schema (which covers return structure) and comprehensive annotations, the description completes the picture with usage alternatives, parameter nuances, permissions, and reliability guarantees. The tool is simple (2 optional params), and this description fully covers the necessary context.

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?

While the schema already provides descriptions for both parameters (100% coverage), the description enriches semantics by explaining inclusiveness, the ordering constraint (startDate <= endDate), and the default behavior when both are omitted. This adds meaning 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 clearly states the tool 'Get n8n's official instance insights aggregates', specifying both the action (get) and the resource (instance insights aggregates). It distinguishes itself from the sibling tool n8n_introspect by clarifying it's for instance-level aggregates vs. single workflow diagnostics.

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?

Provides explicit usage guidance: 'Use it when the Community endpoint exists' and 'use n8n_introspect for one workflow's diagnostics'. It also explains parameter usage conditions (inclusive bounds, startDate <= endDate, default range when omitted), giving clear context for when to invoke.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds key behavioral context: '23 deterministic local rules,' 'never executes or calls AI,' 'requires workflow/execution read permission,' and 'returns findings and coverage.' This enriches the agent's understanding of safety and output.

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 well-structured and concise. It front-loads the core purpose, then compactly explains profile behaviors, label options, alternatives, and safety guarantees. Every sentence provides value with no filler.

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?

Given the tool's moderate complexity, the presence of a full input schema and output schema, and clear annotations, the description is complete. It covers purpose, usage distinctions, behavior, and permissions, leaving no critical gaps for the agent to resolve.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: profile sets paired defaults (quick 24h/20 capped at 25; deep 168h/50 with at most four redacted details), and includeSanitizedLabels semantics are clarified. This helps the agent choose parameters correctly.

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 opens with a specific verb and resource: 'Inspect one workflow and saved executions with 23 deterministic local rules.' This clearly states what the tool does and differentiates it from siblings by explicitly naming alternatives like n8n_audit_generate and n8n_workflows_get for other use cases.

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 explicit guidance on when to use this tool versus alternatives: 'Use n8n_audit_generate for instance security or n8n_workflows_get for raw structure.' It also describes profile-based usage (quick for metadata triage, deep for redacted details) and notes the required permission.

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

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

Annotations already declare readOnly=true and non-destructive, but the description goes beyond by disclosing the required 'workflow-list permission,' the return content ('counts and exact coverage'), and execution caps ('30 seconds or 20,000 nodes'). It also explains that active and limit apply to every page, which is non-obvious behavior. No contradiction with annotations.

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?

Four sentences, each carrying meaningful information. The description is front-loaded with the core purpose and then delivers concise operational guidance. Every sentence earns its place without redundancy.

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?

Given the tool's pagination complexity and the existence of an output schema, the description covers all necessary context: how to obtain complete coverage, the permission required, execution caps, and the relationship to a sibling tool. No critical gaps remain.

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?

The input schema already covers all four parameters at 100% description coverage, so the baseline is 3. The description adds useful semantics beyond the schema: how cursor, maxPages, active, and limit interact during pagination, and that limit/active must remain stable across calls. This raises it to a 4.

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 opens with a specific verb+resource: 'Inventory node types observed across workflow pages,' which clearly states what the tool does. It also distinguishes itself from siblings by explicitly noting 'this proves usage, not installation' and pointing to n8n_get_node_docs for bundled references, so there is no ambiguity about its scope.

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?

Provides explicit pagination guidance: 'Omit cursor to start at page one,' 'maxPages limits how many pages this call follows,' and 'keep them unchanged when continuing from nextCursor.' It also names an alternative tool ('Use n8n_get_node_docs for bundled references') and states the prerequisite permission, making the intended usage very clear.

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

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

Annotations already mark the tool as read-only and idempotent, but the description adds substantial context: local-only matching within searchIn fields, upstream active filtering, a 50-result cap, 'value-free matches,' explicit scan state, and permission requirements. This is rich behavioral disclosure that the annotations alone do not provide.

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 every sentence earns its place: it covers functionality, filter semantics, pagination instructions, an alternative, a permission note, and return behavior in four tightly-woven sentences. It is front-loaded with the core purpose and avoids redundant or filler language.

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?

Given the tool's complexity (pagination, local filtering, permission, cap, and explicit scan state), the description covers all essential aspects without needing to explain return values (since an output schema exists). It is fully self-contained for correct selection and invocation.

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?

Even though schema coverage is 100%, the description surpasses schema descriptions by explaining the interaction between query and searchIn ('query is matched locally only in the fields named by searchIn') and by adding critical semantics for cursor usage and the 50-match cap, which affects the meaning of the limit parameter. This provides genuine additional value beyond the 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 opens with 'Search one workflow page for a case-insensitive substring,' a specific verb+resource+scope combination that immediately conveys what the tool does. It also distinguishes itself from the sibling n8n_workflows_list by explicitly stating 'This is not a global index; use n8n_workflows_list for an unsearched page.'

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?

Provides clear when-to-use and when-not-to-use guidance: it directs users to n8n_workflows_list for unsearched pages, explains the pagination contract ('Omit cursor for page one, then keep query, searchIn, active, and limit unchanged when passing nextCursor'), and states the required permission ('workflow-list permission'). This goes beyond implicit usage and identifies alternatives.

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

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

Goes well beyond annotations by disclosing that it is an additive write, does not handle duplicate names (left to n8n), never assigns to workflows, and returns validated metadata. It also specifies permission needs, which is critical for a mutation tool. No contradiction with annotations.

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?

Three sentences, each packed with distinct information: core action, parameter clarification, and usage/alternatives/permissions. No redundant phrases; the most critical purpose appears first.

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?

The description fully covers the tool's purpose, parameter nuance, safety profile, permissions, and relationship to sibling tools. Since an output schema exists, not detailing return values is acceptable. It is complete for a simple create operation.

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?

Even though schema coverage is 100%, the description adds meaning by clarifying that 'name' is a literal display label, not a tag ID or assignment, and must already be trimmed. This prevents misuse of the sole parameter, which is valuable beyond the schema's basic string constraints.

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 opens with 'Create and persist one reusable workflow label as an additive write,' which is a specific verb and resource. It clearly distinguishes from sibling tools by clarifying it does not assign tags to workflows and pointing to n8n_tags_update and n8n_workflows_update_tags for related operations.

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?

Explicitly states when to use alternatives: 'Use n8n_tags_update for an existing tag and n8n_workflows_update_tags to assign it.' Also emphasizes that creation never assigns tags, so we know this tool is only for creating standalone labels. Permission requirements (write/unsafe mode + create permission) set clear usage prerequisites.

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

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

Discloses permanent deletion, cascade effect on many workflows, no rollback, required unsafe mode, and the return value (tagId with deleted=true). This adds significant context beyond the destructiveHint annotation, covering the full behavioral profile of a high-risk operation.

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?

Three tightly packed sentences, each serving a distinct purpose: impact, parameter constraint, and guidance with rollback/permission/return. Eminently concise with zero filler.

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 dangerous single-param delete tool, it covers side effects, permission requirements, preconditions, alternatives, rollback, and return value. With output schema present, the description leaves no meaningful gaps.

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 description is 100% covered, but the tool description adds critical semantic detail: tagId must come specifically from n8n_tags_list or get and cannot be a tag name or workflow ID. This prevents a class of common misuse beyond what the schema's pattern alone conveys.

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 action: 'Permanently delete one workflow tag' and its impact on multiple workflows. It distinguishes from sibling tools by explicitly naming n8n_tags_update as an alternative when a rename suffices.

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?

Clear guidance on when to use: requires review of affected workflows, explicit alternative (n8n_tags_update), and prerequisites like unsafe mode and tag-delete permission. Also specifies that tagId must be the stable ID from n8n_tags_list or get, not a name or workflow ID.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral context: it requires tag-read permission, returns a specific set of fields (validated ID, name, optional timestamps), and clarifies that the ID represents the reusable tag itself rather than an assignment, preventing a common misunderstanding. No contradictions with annotations.

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 compact and front-loaded, opening with the core purpose. Each sentence adds distinct useful information: identity source, usage timing, semantic distinction, permissions, and return fields. No fluff or repetition, making it easy for an agent to parse quickly.

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?

Given the tool's low complexity (single required parameter, no nested objects) and the presence of an output schema, the description sufficiently covers all necessary context: permissions, return contents, and conceptual boundaries. It is complete for an agent to correctly select and invoke the tool.

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?

The input schema already provides 100% coverage for the single parameter with a clear description and pattern. The tool description adds extra semantic value by specifying the ID source (n8n_tags_list or create) and explicitly rejecting alternatives like names or workflow IDs, which goes beyond the schema's basic description.

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 opens with a clear verb+resource construction ('Get one workflow tag'), explicitly scopes the operation to a single tag, and distinguishes it from related operations like listing or modifying tags. It further clarifies what the tool does not do (list or change assigned workflows), eliminating ambiguity.

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 explicitly states when to use this tool ('Use it before assigning, renaming, or deleting the tag') and provides clear exclusions: a tag name or workflow ID is not accepted, and it neither lists nor changes assigned workflows. It also names n8n_tags_list/create as sources for obtaining the required tagId, effectively guiding the agent toward alternative tools for other scenarios.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals a permission requirement ('Requires tag-list permission'), confirms side-effect freeness ('never changes assignments'), and states the return contents ('validated metadata and nextCursor'). It adds meaningful operational detail that annotations do not encode.

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?

Three dense sentences, each earning its place: core action, pagination behavior, alternative tool, permission, and return summary. The most important information is front-loaded, with zero filler.

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?

The description covers the core scope, pagination loop, alternative tool, required permission, and side-effect guarantees. Combined with an output schema and clear annotations, there is nothing material left for an agent to guess.

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?

The schema already documents limit and cursor well (100% coverage), but the description adds operational meaning beyond that: the cursor should be passed back unchanged for later pages, and limit only affects the current page. This gives agents concrete execution strategy not present in the 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 opens with 'List one Public API page of workflow tags,' which is a specific verb+resource+scope statement. It clearly differentiates from sibling n8n_tags_get by the page-level scope and by explicitly naming that alternative.

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?

It provides explicit pagination guidance: 'Omit cursor for page one; for later pages, pass nextCursor back unchanged' and tells when to stop ('continue until nextCursor is null'). It also names an alternative, 'Use n8n_tags_get when the stable tag ID is known,' so agents know when to pick a different tool.

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

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

Annotations already mark this as read-only=false and destructive, and the description adds valuable context: permission requirements ('requires write/unsafe mode plus tag-update permission'), the stable selector nature of tagId, and a note that duplicate-name acceptance is backend-controlled. This goes beyond the structured annotation fields without contradicting them.

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 compact and front-loaded, with the core purpose in the first sentence. Each subsequent sentence adds distinct value: parameter clarification, usage exclusions, and permission/return details. No redundant or filler content.

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 only two simple parameters, the description covers purpose, usage boundaries, permission requirements, ID semantics, and return type. The presence of an output schema further reduces the need to detail return fields, so the description is fully sufficient.

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% for both parameters, so the baseline is 3. The description adds extra meaning by clarifying that tagId is the 'stable selector from n8n_tags_list or get' and that name is the 'complete new display label, not another ID', which helps prevent misuse beyond the schema's basic descriptions.

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 uses a specific verb ('Rename') and resource ('existing workflow tag') while explicitly stating it preserves ID and assignments. It clearly distinguishes itself from siblings by naming n8n_tags_create and n8n_workflows_update_tags for related but different actions.

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?

Provides explicit when-to-use ('Rename one existing workflow tag') and when-not-to-use instructions: 'Use n8n_tags_create for a new label and n8n_workflows_update_tags to change assignments.' This directly answers the alternatives question.

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

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

Beyond annotations (destructiveHint=true), the description discloses non-atomic full-workflow PUT, permissions required (write/unsafe mode, read, update), returns residual race risk, and that it preserves sibling data. This adds significant behavioral context.

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?

Three sentences, front-loaded with the core action, then necessary details, alternatives, and permissions. No wasted words.

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?

Covers purpose, usage, alternatives, safety guards, permissions, and return value. Given the output schema and annotations, nothing important is missing.

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?

Even though schema coverage is 100%, the description enriches parameter meaning by explaining the role of each parameter: workflowId selects the workflow, nodeId selects exactly one node, path selects the mutable field, expectedVersionId must be copied from the latest read, and acknowledgeNonAtomicRisk is a required guard.

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 clearly states 'Update one path on one node' with a specific verb and resource, and explicitly distinguishes itself from n8n_workflows_update by noting it preserves sibling data and targets a single node.

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?

It provides explicit when-to-use and when-not-to-use guidance: 'Use n8n_workflows_update for top-level or multi-node edits.' It also details prerequisites like copying expectedVersionId and setting acknowledgeNonAtomicRisk=true.

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

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

Discloses non-obvious side effects: may send email, 'additive write', inconclusive responses may still result in a pending user, and the return value never includes the acceptance URL. This adds significant behavioral context beyond the annotations (which only indicate readOnlyHint=false, openWorldHint=true, etc.) and aligns with them.

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 densely packed but highly structured: action, side effects, parameter guidance, preconditions, and failure semantics in five sentences. No redundant words; every sentence contributes critical information.

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?

Given the tool's mutation side effects, permission requirements, and ambiguity of outcome, the description covers preconditions, parameter implications, and return-value limitations. The presence of an output schema means it doesn't need to list response fields, so it is complete for an AI agent's decision-making.

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?

Although the schema already covers both parameters with descriptions (100%), the description adds domain meaning: email as the future account login, role's distinction from project membership, and omission behavior. This enhances understanding beyond the enum and default values.

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 clearly states the tool creates a pending invitation (additive write) and may send email. It distinguishes from sibling tools like n8n_users_get and n8n_users_list by specifying the create/invite action and pending-invitation semantics.

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?

Explicitly instructs to call n8n_users_get first when the user may already exist, warns that owner invitations are rejected, and states required permissions (unsafe mode + invite permission). This gives clear when-to-use and when-not-to-use context beyond simple tool selection.

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

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

Beyond the destructiveHint annotation, the description discloses permanent deletion, the non-acceptance of email addresses, lack of a transfer target, required unsafe mode and permission, and the absence of a rollback claim. These are critical behavioral details not present in the annotations.

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 four concise sentences, with the main purpose front-loaded. Every sentence earns its place by providing either a prerequisite, an identity constraint, a verification step, or a behavioral consequence—no filler or repetition.

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?

Given a single parameter, rich annotations, and an output schema, the description fully covers prerequisites, ID sourcing, verification, permission requirements, and return behavior. It leaves no significant ambiguity about how to invoke the tool correctly.

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?

Although the schema provides a stable ID description with a pattern, the description adds crucial semantics: the userId must come from n8n_users_list or get, and an email address is not accepted. This prevents a common misuse and goes well beyond the schema's baseline.

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 opens with 'Permanently delete one API-eligible user,' using a specific verb and resource while distinguishing this from sibling delete tools. It further clarifies the identity requirement (stable ID, not email), making the tool's purpose unmistakable.

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?

It explicitly instructs the agent to obtain userId from n8n_users_list or get and to verify the target with get first. It also states required permissions (unsafe mode, user-delete permission) and implies when not to use it by noting there is no transfer target and no rollback claim.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses routing logic (ID-shaped vs email input), exact percent-encoded email lookup, no partial matching, includeRole caveats, permission requirements, and redaction-protected returns. This thoroughly covers behavioral nuances.

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?

Three dense sentences, each earning its place. The description is front-loaded with the core action and immediately provides needed context on routing, alternatives, permissions, and safety. No filler.

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 simple get-by-identifier tool, the description comprehensively covers input handling, alternative tools, permissions, and output characteristics. The presence of an output schema reduces the burden of explaining return values, and the description works well with the structured metadata.

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?

While the schema covers 100% of parameters, the description adds meaningful semantics: how userIdOrEmail is routed based on input shape, the percent-encoding requirement, and the behavior of includeRole. This goes beyond the schema's basic field descriptions.

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 clearly states the verb (Get), resource (user), and qualifiers (by stable ID or exact email). It distinguishes itself from sibling tools like n8n_users_list by explicitly noting that n8n_users_list is for discovery, making the purpose unambiguous.

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 explicit when-to-use guidance (by ID/email) and directs users to n8n_users_list for discovery, which is a clear alternative. It also notes the required user-read permission, adding practical usage context.

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

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

Adds rich behavior beyond annotations: includeRole may be omitted by permission, cursor resumes one prior page and never auto-paginates, permission requirement, and returns redaction-protected metadata. No contradiction with readOnlyHint or other annotations.

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?

Three dense sentences, front-loaded with the core purpose, then usage guidance, then behavioral details. Every sentence contributes unique value with no filler or redundancy.

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?

The description covers purpose, alternatives, permissions, pagination behavior, and return metadata (nextCursor). With an output schema present, return values need not be detailed; this description is complete for a simple list tool.

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%, but the description enriches parameters: includeRole behavior ('may still be omitted by permission') and cursor behavior ('resumes one prior page and this call never auto-paginates') go beyond the schema descriptions, adding valuable edge-case context.

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 action and resource: 'List one Public API page of users.' It also distinguishes from sibling tool n8n_users_get by noting when to use that alternative, making the purpose unambiguous.

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?

Provides explicit guidance: 'Use it for discovery; use n8n_users_get when a stable ID or exact email is known.' It also mentions the required permission, giving clear when-to-use and alternative conditions.

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

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

The description adds meaningful behavioral context beyond annotations: 'this does not execute it now' clarifies the timing of effects, and 'returns target-validated active state metadata' describes the output. It also states permission requirements. This complements the annotations (destructiveHint=true, openWorldHint=true) without contradicting them, giving the agent a full picture of side effects and preconditions.

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 compact and front-loaded: the first sentence states the core purpose, and the following three sentences each deliver a distinct piece of critical guidance (ID source, deactivation alternative, permissions/output). No wasteful or redundant wording.

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 single-parameter tool with an output schema, the description covers all necessary context: what activation means, what it does not do, how to obtain the correct ID, alternative tool for reversal, required permissions, and what is returned. This is complete for an agent to safely and correctly invoke the tool.

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?

The schema already provides a description for workflowId, but the tool description adds essential semantics: 'workflowId must be the current stable ID from n8n_workflows_list or get, not a name or version ID.' This goes beyond the schema's generic 'Stable ID of the workflow to activate' by clarifying provenance and exclusivity, significantly improving parameter understanding.

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 clearly states the action: 'Activate one workflow so production triggers can accept future events'. It uses a specific verb (activate) and resource (workflow) and distinguishes itself from the sibling n8n_workflows_deactivate by explaining the effect on triggers. It also clarifies that activation does not execute the workflow immediately.

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?

Explicit when-to-use guidance is provided: 'Review the workflow first; use n8n_workflows_deactivate to stop future triggers.' It also specifies the exact source and type of workflowId ('must be the current stable ID from n8n_workflows_list or get, not a name or version ID') and prerequisites ('Requires unsafe mode plus activation permission'). This leaves no ambiguity about when or how to use the tool.

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

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

The description adds context beyond the destructiveHint annotation by explaining the exact effect: archiving preserves the saved definition but makes the workflow unavailable. It discloses side effects (disruption to callers), permission requirements, and the return value (isArchived=true), providing a complete behavioral picture without contradicting annotations.

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 compact yet information-dense. Every sentence serves a purpose: action, parameter clarification, usage guidance, side-effect warning, and permission/return-value context. No redundancy or filler exists.

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?

Given the simple schema (one parameter) and rich annotations, the description fully completes the picture. It covers purpose, parameter source, alternatives, permissions, side effects, and return metadata. An output schema exists, so return values are also structured, making this comprehensively complete.

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?

The schema already contains a clear description for workflowId, but the description enriches it further: 'workflowId must be the current stable ID from n8n_workflows_list or get, not a name or version ID.' This clarifies how to obtain the correct value and what values to avoid, adding meaning beyond the schema's brief definition.

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 the specific action: 'Archive one workflow without deleting its saved definition.' It clearly distinguishes this from sibling tools like delete (reversible removal) and deactivate (stop triggers), providing a precise verb+resource+scope.

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?

Explicit guidance is given: 'Use this instead of delete for reversible removal; use deactivate only to stop triggers.' It also states prerequisites (unsafe mode plus archive permission) and warns about operational impact (availability change can disrupt callers), leaving no ambiguity about when to choose this tool.

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

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

The description discloses key behavioral traits: additive write, no trigger activation, default settings object behavior, and return value characteristics ('returns the validated projection without pin/static values'). This goes beyond the annotations (which only indicate not read-only, open world possibility, etc.), and there is no contradiction with annotations.

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?

Three sentences cover action, constraints, alternatives, permissions, and return value — dense and efficient. No redundant wording, and the most critical information (create, no triggers) appears first. Every sentence earns its place.

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?

Despite 8 parameters and nested structures, the description covers the essential operational context: additive creation, graph constraint, permission requirements, and return projection. With the rich input schema and an output schema available, the description adequately fills the contextual gaps, making the tool complete for agent decision-making.

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 baseline is 3. The description adds conceptual value by stating that 'nodes and connections must form one complete graph' and that optional fields are 'forwarded only when supplied,' clarifying the parameter relationships. It also notes 'omitting settings uses an empty object,' which is consistent with the schema default. While not deeply detailing every parameter, it provides meaningful contextual semantics beyond the schema descriptions.

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 clearly states the tool creates and persists a new workflow ('Create and persist one workflow'), specifying it is an 'additive write' and explicitly excludes trigger activation, which distinguishes it from update and activate siblings. The verb and resource are specific and unambiguous.

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 explicitly says 'Use n8n_workflows_update for an existing workflow and activate for triggers,' naming the exact alternative tools and providing a strong condition for when not to use this tool. It also states the required mode and permission ('Requires write or unsafe mode plus create permission'), giving clear usage guidance.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description clarifies the actual behavioral impact: it does not delete saved data or stop runs in progress. It also discloses the permission requirement and the return value ('target-validated inactive state metadata'), adding substantial context that the annotations alone do not convey. No contradiction with annotations.

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 four sentences, front-loaded with the primary action. Every sentence contributes distinct value: what it does, the ID requirement, alternatives, and permissions/return. There is no fluff or repetition of schema or annotation data.

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?

Given the tool has only one parameter, a full output schema, and annotations, the description covers all necessary context: side effects, preconditions, ID source, and alternatives. It is complete for an agent to select and invoke the tool correctly without additional probing.

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?

Although the schema provides 100% coverage for workflowId with a description and pattern, the tool description adds crucial semantics: the ID must be the current stable ID from n8n_workflows_list or get, and it explicitly excludes name or version IDs. This prevents a common misuse and goes far beyond the schema's generic description.

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 ('Deactivate') with a clear resource ('one workflow's future production triggers') and scope, distinguishing it from the sibling tools n8n_workflows_activate and n8n_workflows_archive. It also clarifies what it does not do (delete saved data or stop in-progress runs), leaving no ambiguity about its purpose.

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?

Explicitly advises when to use alternatives: 'Use n8n_workflows_activate to reverse the state or archive for lifecycle removal.' It also provides a critical precondition (unsafe mode and deactivation permission) and specifies the exact source of workflowId ('current stable ID from n8n_workflows_list or get, not a name or version ID'), offering complete usage guidance.

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

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

Annotations already indicate destructive and non-idempotent behavior. The description adds crucial context: 'no rollback or transfer', requires 'unsafe mode plus delete permission', and the exact response format ('returns the request-bound workflowId with deleted=true'). This goes beyond annotations.

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?

Three dense sentences, each earning its place: purpose, ID requirements, alternatives, consequences, permissions, and return value. No filler or redundancy.

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 simple 1-parameter delete operation with a single required param and output schema, the description covers all necessary aspects: action, input requirements, alternatives, side effects, permissions, and response. There are no missing gaps.

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?

The schema already describes workflowId as 'Stable ID of the workflow to delete' (100% coverage). The description adds significant semantic value by specifying the ID source (from list or get) and excluding name/version IDs, which is not evident from the 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 clearly states the action: 'Permanently delete one workflow and its saved definition.' It specifies the exact resource (workflow) and the permanent nature, distinguishing it from related tools like archive.

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?

Explicit guidance is provided: workflowId must be the current stable ID from list or get, not a name or version ID. It also directs users to alternative tools (archive for reversible removal, get for inspection), making when-to-use extremely clear.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral details: it returns 'coverage, counts, and a byte-bounded prefix of up to 200 changes,' requires 'workflow/history read permission,' and clarifies that ignoreLayout hides position-only changes. This goes well beyond the structured data.

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 three sentences, front-loaded with the core purpose, and every sentence adds essential information. There is no redundancy or padding. It efficiently packs parameter semantics, alternatives, permissions, and output characteristics into a compact, readable format.

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?

Given the output schema and 100% parameter schema coverage, the description complements rather than repeats structured data. It mentions the high-level return values (coverage, counts, prefix) and permission requirements, making the tool's behavior fully understood without over-explaining. The context signals and sibling list further support usage decisions.

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?

While the schema descriptions already cover 100% of the parameters, the description enriches their meaning by explaining relationships: workflowId selects the workflow, fromVersionId is the retained baseline, toVersionId is an optional target, and omitting toVersionId compares with current state. It also clarifies the semantics of ignoreLayout. This adds significant value over the 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 opens with a specific verb and resource: 'Compare two states of one workflow without returning changed values.' This clearly defines the tool's function. It also distinguishes from the sibling tool by explicitly directing users to n8n_workflows_get_version for raw history, making the purpose unambiguous.

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 clear context for when to use the tool, such as omitting toVersionId to compare with the current state, and names an alternative (n8n_workflows_get_version) for raw history. However, it does not explicitly state when NOT to use this tool, but the guidance is sufficient for effective selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond that: the subtle behavior of excludePinnedData (it only affects the upstream request and presence flags, but pinned values are withheld regardless) and the permission requirement. This is useful, non-obvious behavioral detail that annotations do not convey.

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 three dense sentences with no fluff. It front-loads the purpose, then addresses usage, then a behavioral nuance. Every sentence adds information without redundancy.

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 simple read-only get tool, this is complete. It covers what the tool does, how to specify the ID, the behavioral nuance of excludePinnedData, permission needs, and the alternative for version history. Since an output schema exists, return values are adequately documented elsewhere.

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 descriptions already cover both parameters (100% coverage), so baseline is 3. The tool description adds practical context: workflowId is the stable ID returned by list/create (not a name or version), and excludePinnedData changes only the request and presence flags while output still withholds pinned data. These clarifications go beyond the schema field descriptions.

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 opens with 'Get one current workflow for inspection or reviewed editing,' which clearly states the action (get), the resource (current workflow), and the singular scope (one). It distinguishes from sibling tools like n8n_workflows_get_version by explicitly directing version history elsewhere, and from list tools by being a single-item retrieval.

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?

It explicitly names n8n_workflows_get_version as the alternative for history, and clarifies that workflowId is a stable ID from list/create, not a name or version ID—preventing misuse. It also states the permission requirement, giving the agent clear preconditions for when this tool is appropriate.

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

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

Annotations already cover safety (readOnly, idempotent, not destructive). The description adds valuable context beyond annotations: the endpoint has no cursor and keeps at most 100 records with exact omissions, requires assignment-read permission, and returns validated tag metadata. This gives the agent critical operational knowledge.

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?

Four sentences, each carrying distinct information: purpose, parameter semantics, usage guidance, and behavioral limit/permission. There is no redundancy or filler, and the most important statement is front-loaded.

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 simple single-parameter read tool with an output schema, the description covers everything: what it does, when to use it, what to know about limits and permissions, and parameter clarification. The output schema covers return values, so no additional return explanation is needed.

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 covers the parameter at 100%, but the description adds meaning by clarifying that workflowId is the workflow selector from n8n_workflows_list or get, and explicitly warns it is not a tag ID. This prevents a likely misuse even though the schema already describes the parameter.

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 opens with a specific verb+resource+scope: 'List tags currently assigned to one workflow.' It actively distinguishes from siblings by noting this is not n8n_tags_list ('use n8n_tags_list for all tags') and clarifying that workflowId is not a tag ID.

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?

Explicit guidance is given: use before n8n_workflows_update_tags when assignments must be preserved, and use n8n_tags_list for all tags. This tells the agent both when to choose this tool and when to choose an alternative, making the decision clear.

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

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

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses that a missing endpoint and a pruned version share an ambiguous 404 outcome, that history-read permission is required, and that the response contains validated nodes and connections subject to retention. This adds substantial behavioral context.

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 concisely written with six short sentences, each adding essential information. It is front-loaded with the core purpose and contains no fluff or redundant statements.

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?

Given the tool's complexity, the presence of an output schema, and the annotations covering safety, the description fully compensates by covering permissions, edge-case error behavior, ID relationships, and alternatives. It is complete for effective selection and invocation.

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?

Although the schema has 100% coverage with descriptions for both parameters, the description adds crucial semantic meaning by clarifying the distinct roles of workflowId vs versionId and explicitly instructing not to swap them or pass a workflow name. This goes beyond the schema to prevent common misuse.

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 clearly states the tool gets one retained workflow snapshot, with a specific verb and resource. It explicitly distinguishes from sibling tools n8n_workflows_get (current state) and n8n_workflows_diff (comparison).

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?

It provides explicit guidance on when to use this tool versus alternatives: 'Use n8n_workflows_get for current state or n8n_workflows_diff for comparison.' It also warns against swapping IDs or passing a workflow name, and states the permission requirement.

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

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

Beyond the readOnly/idempotent hints in annotations, the description discloses important behaviors: the result is a single page, pagination is manual, it requires the workflow-list permission, and output is projected to exclude pin/static values. This adds valuable operational context without contradicting annotations.

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?

Three tightly packed sentences deliver purpose, alternatives, pagination rules, permissions, and return-value expectations. The content is front-loaded with the core action and every sentence provides distinct value with no redundancy.

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?

Given the output schema exists, the description does not need to repeat return formatting. It covers pagination, filter semantics, permission requirements, and output projection, which fully addresses the tool's complexity and its relationship to sibling tools.

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 description coverage is 100%, so the baseline is 3. The description enhances this by explaining cross-parameter behavior: filters are combined upstream and must remain unchanged when passing nextCursor, and limit only sizes the current page. This adds meaning beyond individual parameter schemas, though not every parameter is addressed in the free text.

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: 'List one Public API page of workflows visible to the configured API key.' It also explicitly distinguishes itself from siblings by naming n8n_search_workflows for substring matching and n8n_workflows_get for a known ID, leaving no ambiguity about its scope.

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?

Usage guidance is explicit and practical: it tells when to use alternatives, how to handle the cursor ('Omit cursor for page one'), that filters must be preserved when passing nextCursor, and that the tool never auto-paginates. This provides clear context for selection and correct invocation.

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

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

Beyond annotations, the description discloses important behavioral traits: it does not activate triggers, it requires the archived workflow ID specifically (not a name or version), it does not infer current active state, and it returns 'target-validated metadata with isArchived=false'. This adds significant context and clarifies side effects and permissions.

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 concise and front-loaded. The core purpose appears in the first sentence, and each subsequent sentence earns its place by adding necessary constraints, usage context, or behavioral caveats. No filler or repetition.

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?

Despite having an output schema, the description still provides a complete operational picture: prerequisites (unsafe mode and permission), required identifier semantics, trigger behavior, and a summary of the returned metadata. For a single-parameter mutation tool, this is fully sufficient and leaves no critical gap.

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% and the schema already describes workflowId as a 'Stable ID of the workflow to restore from archive.' The description adds valuable nuance by clarifying that workflowId must identify the archived workflow itself, not a name or version ID. This goes beyond the schema's minimal description, though the schema covers the basic meaning.

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 clearly identifies the action ('Restore one archived workflow'), the resource, and a key non-goal ('without activating its triggers'). It also distinguishes itself from sibling tools like n8n_workflows_archive and n8n_workflows_activate by explicitly framing itself as the reverse operation.

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 explicit guidance: 'Use this to reverse n8n_workflows_archive' and tells when NOT to use it ('call activate separately only if triggers should resume'). It also states the prerequisite 'unsafe mode plus unarchive permission', giving clear context for when this tool is appropriate.

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

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

Despite annotations already marking destructiveHint and readOnlyHint, the description adds substantial non-obvious behavior: non-atomic full PUT semantics, field preservation vs. whole-array/object replacement, version-matching requirements, permission needs ('write/unsafe mode plus read and update permission'), and confirmation of the returned projection. No contradictions with annotations.

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?

Every sentence earns its place. The description front-loads the main action, then packs prerequisites, replacement semantics, alternatives, permissions, and return value into a compact but highly informative block. No fluff or redundancy.

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?

Given the tool's complexity (10 params, nested objects, output schema present), the description covers all critical operational aspects: identification, versioning, replacement semantics, alternatives, permissions, and return value. The output schema already handles return details, and the description exceeds what is necessary.

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 baseline is 3. The description adds meaningful semantics beyond the schema: workflowId 'selects the current record', expectedVersionId must be copied from the latest read and 'must match both pre-write reads', and the crucial behavior that 'each supplied array or object replaces that whole field.' This justifies a score above baseline.

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 opens with 'Update selected top-level fields through a non-atomic full PUT,' which clearly states a specific verb, resource, and HTTP method. It further distinguishes itself from siblings by name: 'Use n8n_update_node for one node property and n8n_workflows_update_tags for tags.'

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?

Provides explicit when-to-use guidance, including the exact alternative tools for narrower operations and the prerequisite to 'copy expectedVersionId from its latest read.' It also clarifies the need to 'supply at least one writable field' and that version must match pre-write reads.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds concrete behavioral details: omitted IDs are removed, [] clears all tags, permission requirements ('write/unsafe mode plus assignment permission'), and the return value ('validated replacement'). These are material side effects the agent needs to know.

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 four sentences, each earning its place: purpose/scope, parameter sourcing, replacement semantics, and permission/return. It is front-loaded with the most important operational constraint and contains no filler.

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?

The tool is a hazardous write operation (destructiveHint=true), and the description covers the full operational context: how the parameters interact, the destructive side effect, required permissions, safe order of operations (get_tags first), and return value. This is complete guidance for correct invocation.

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?

Although schema coverage is 100%, the description adds essential meaning beyond the schema: tag IDs must be stable IDs from n8n_tags_list or get and tag names are not accepted. It reinforces the 'whole desired set' semantics by stating omitted IDs are removed, which is not fully captured by 'complete replacement list' in the 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 opens with a specific verb and resource: 'Replace one workflow's complete tag assignment,' clearly indicating the tool's purpose. It explicitly distinguishes from 'merge' behavior, and the title/description align, separating it from related workflow/tag tools.

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 explicitly tells the agent when to use the tool (to replace the complete tag set), when not (not a merge), and names the prerequisite alternative: 'Use n8n_workflows_get_tags first to preserve assignments.' It also directs the agent to n8n_tags_list or get for stable tag IDs.

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