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

Annotations already indicate a safe read-only, idempotent operation. The description adds meaningful behavioral detail: output is a unified diff with a defined ordering, and default behavior when only the node is supplied. This goes beyond the annotation-provided safety profile.

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 concise sentences deliver the core purpose and defaults with no filler. The most important information is front-loaded, and 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?

For a read-only diff tool with full schema coverage, an output schema, and safety annotations, the description covers the essential behavior and default invocation. There is no critical information an agent needs to call it correctly that 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?

Schema description coverage is 100%, so the schema already documents all six parameters, including defaults and meanings. The description reinforces the base_oid-to-oid direction, but does not add significant meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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 operation: showing what changed in a node's configuration between two versions, specifically via a unified diff. It distinguishes itself from siblings like get_node_version and get_node_config by focusing on comparison rather than 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?

The description provides clear context for use, including the diff direction (base_oid older to oid newer) and the no-argument behavior of showing the most recent change. It does not explicitly name alternatives or exclusion cases, but the usage context is unambiguous.

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 and idempotent, so the description adds value by disclosing result ordering (exact, prefix, then substring) and case-insensitive matching. These are meaningful behavioral traits not visible in the schema or 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 short sentences with no filler. The core lookup behavior is first, the workflow use is second, and the ordering/case details close it out efficiently.

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 two-parameter read-only search tool with an output schema and full schema coverage, the description provides everything needed: what to search, why to use it, and how results are ordered. No critical gap remains.

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%: both query and limit are documented there, including the full set of query forms (part of a name, full name, IP address). The description mostly restates the query semantics rather than adding new parameter-level detail.

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 a specific verb and resource: 'Find nodes' by partial name, full name, or IP address. The phrase 'resolve an ambiguous device name before calling other tools' clearly distinguishes it from siblings like list_nodes or get_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?

Gives clear context: use it to resolve ambiguous node names before invoking other tools. It does not explicitly name alternatives or give when-not-to-use guidance, but the intended placement in a workflow is 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?

The description adds significant context beyond the readOnly/idempotent annotations: it defines 'stale' precisely (last backup attempt, not success), explains that Oxidized does not expose last successful backup time, notes that run history is in-memory and resets on restart, and warns that a node may briefly show as never backed up right after trigger_node_backup. These are critical behavioral quirks an agent must know to interpret results correctly.

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 a bit long but every sentence carries useful information. It is front-loaded with the core summary, then explains the stale definition and important caveats. While it could be trimmed slightly, the length is justified by the need to convey data-source limitations and behavioral quirks. 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?

Given the tool's complexity (multiple optional filters, nuanced data-source limitations) and that an output schema exists, the description covers all essential context: data source, what counts are computed, the stale definition, and known edge cases (after trigger_node_backup). The output schema handles return format, so no need to describe it. An agent has everything needed to call it correctly and interpret results.

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 all four parameters are fully documented in the schema. The description does not add parameter-specific details beyond what the schema provides; it only mentions 'optionally limited to one group or model' and clarifies the stale threshold concept, which is already in the schema. Baseline of 3 is appropriate since the schema does the heavy lifting.

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: 'Summarise backup health across Oxidized nodes.' It specifies the exact resource (backup health across nodes) and the action (summarise). It also lists the specific outputs (counts, success rate, lists of failed/never/stale nodes), distinguishing it from sibling tools that handle node listing, config retrieval, or backup triggering.

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 implicitly tells the agent when to use this tool: when backup health metrics are needed, explicitly noting that oxidized-web's own stats JSON is not usable. It does not name alternatives or give explicit when-not-to-use conditions, but the unique purpose among siblings makes the usage context clear. It also explains filtering by group/model, giving a sense of optionality.

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, so the safety profile is clear. The description adds value by specifying the exact return fields (name, full name, IP, group, model, vars, last backup run details), which is useful behavioral context. However, it doesn't disclose potential errors (e.g., node not found) or any rate limits, but given the annotations, a 3 is appropriate.

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 two sentences with no waste. The first sentence states the core function, and the second lists the return fields. It is front-loaded and 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?

Given the tool's simplicity (1 parameter, no nested objects, output schema present), the description is complete enough. It covers what the tool does and what it returns. The only minor gap is not mentioning error cases, but for a read-only single-node fetch, this is acceptable. The output schema likely covers return structure, so the description doesn't need to.

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 schema already documents the 'node' parameter with an example. The description doesn't add much beyond what the schema provides, but it does mention that the node can be identified by name or IP, which aligns with the schema. Baseline 3 is correct since the schema does the heavy lifting.

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 details of a single Oxidized node.' It specifies the resource (a single node) and the verb (get), and distinguishes it from siblings like list_nodes and find_nodes by focusing on a single node's details. The description also enumerates the returned fields, 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 implies usage for retrieving details of a single node, which is distinct from listing or searching nodes. It doesn't explicitly state when not to use it or name alternatives, but the context signals and sibling names provide enough clarity. The description could be improved by explicitly mentioning that this is for a single node, not a list, but the 'single' qualifier already does that.

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 a non-obvious pagination behavior: large configurations are paged by lines, and the caller must follow 'truncated' and 'next_offset' to fetch all data. This adds meaningful behavioral context beyond the readOnly/idempotent annotations and explains exactly how to handle partial results.

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 short sentences: the first states the core purpose, the second gives the necessary paging detail. No wasted words and the most important behavioral 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?

Given the simple, read-only nature of the tool, the fully documented input schema, the output schema, and annotations, the description covers everything needed to invoke it correctly. The pagination caveat is the main non-obvious detail, and it is included.

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 parameters are already documented. The description adds value by clarifying how 'offset' interacts with 'truncated' and 'next_offset', giving the agent a fuller mental model of pagination than the schema alone provides.

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 resource ('latest backed-up configuration of a node') and the action ('Get'), so an agent can understand what the tool returns. It does not explicitly distinguish itself from sibling tools like get_node or get_node_version, though the phrase 'backed-up configuration' narrows the 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?

The description gives no guidance on when to use this tool versus siblings such as get_node, list_node_versions, or get_node_version. The intended use case is only implied by the name and subject matter, with no exclusions or alternative routing.

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 and idempotent, so the description only needs to add operational behavior. It adds the paging mechanism (truncated/next_offset), which is critical for large configurations. It also clarifies that it returns a historical snapshot. 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?

Two sentences, each earning its place. The purpose is stated first, followed by a critical operational detail about pagination. No fluff.

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 read-only historical retrieval tool with an output schema, the description covers the key operational caveat (pagination) and the purpose. It doesn't explain error conditions or version lookup specifics, but those are likely in the output schema or parameter descriptions. Given the complexity, it's adequate.

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 cover all parameters at 100%, so the baseline is 3. The description adds context about paging that relates to offset and max_lines, but doesn't add new semantic meaning to the parameters beyond what the schema already provides. It doesn't explain the 'group' optional behavior beyond the schema's auto-lookup note.

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?

Clearly states it retrieves the configuration of a node at a specific version, distinguishing it from get_node_config (current config) and list_node_versions (version list). The verb 'get' and resource 'configuration of a node' are specific.

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 implies it's for historical config retrieval but does not explicitly state when to use this over get_node_config or diff_node_versions. It lacks explicit alternatives or exclusion conditions, leaving the agent to infer the use case.

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, destructiveHint=false, covering the mutation profile. The description adds meaningful behavioral detail: node vars are redacted unless server redaction is disabled, and filtering is done server-side so only matching nodes are transferred. This goes beyond annotations and helps the agent set 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 a tight two-sentence paragraph. It front-loads the core purpose and return fields, then delivers usage advice and a pointer to an alternative. Every sentence earns its place; 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 read-only listing tool with an output schema already present, the description covers the return shape, filtering behavior, redaction caveat, and large-installation recommendations. Nothing an agent needs to decide when and how to call it is missing. The combination of schema, annotations, and description is fully self-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 description coverage is 100%, so parameters are already documented. The description enriches semantics by explaining when to pass group/model ('on large installations') and clarifies that group matching is exact and case-sensitive, with 'default' selecting nodes without a group. This practical guidance adds 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 starts with a clear verb-resource pair: 'List nodes (network devices) managed by Oxidized.' It then enumerates the exact fields returned (name, full name, IP, group, model, last run status/time, details), making the tool's function unambiguous. It also implicitly distinguishes from siblings by pointing to find_nodes for fuzzy group name lookup.

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 recommends passing group or model filters on large installations and explains why (server-side filtering reduces transfer). It also gives a precise when-not: 'use find_nodes when unsure of the name' for groups, directing the agent to the correct alternative.

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, so the safety profile is covered. The description adds meaningful behavioral context: it lists what each version includes (git oid, date, author, commit message) and the ordering ('newest first'). It also discloses the backend requirement (git/gitcrypt output), which is beyond 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 compact and front-loaded: the main purpose is stated in the first sentence, and the second sentence adds useful detail about the version contents and a prerequisite. Every sentence earns its place, with no fluff or repetition of the schema.

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 a clear purpose, a complete schema, and an output schema, so the description does not need to explain return values. The description covers the key behavioral details (ordering, version contents, backend requirement). It could have explicitly mentioned pagination or the default limit, but the schema already covers the limit parameter, so the description is sufficiently 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a bit of context by mentioning the git oid, date, author, and commit message, which indirectly clarifies what the 'limit' parameter controls, but it does not add significant new meaning beyond the schema. Baseline 3 is appropriate.

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 ('List'), a specific resource ('stored configuration versions of a node'), and a clear ordering ('newest first'). It also distinguishes itself from siblings like get_node_version and diff_node_versions by focusing on the list of stored versions rather than a single version or a diff.

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 clearly implies when to use this tool: when you need the list of stored configuration versions for a node. It also notes a prerequisite ('Requires the Oxidized 'git' (or 'gitcrypt') output'), which is useful context. It does not explicitly name alternatives or exclusions, but the sibling list and the description's focus make the usage context 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 cover idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false). The description adds context by explaining that it reloads every node from the source, replacing the whole in-memory list, and clarifies that per-node reload would be misleading. It also states the return type (Dictionary with response message). This goes beyond annotations 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 concise (three sentences) and front-loaded: it states the primary action and source, then provides usage context, then a caveat, then the return value. Every sentence adds value, with no redundancy or fluff.

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 tool with no parameters and an output schema, the description fully covers purpose, usage timing, behavior, and return type. It also addresses a potential point of confusion (per-node reload) explicitly. Nothing an agent needs to call it correctly 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?

The tool has zero parameters, and schema coverage is 100% (vacuously true). According to the rubric, 0 parameters gives a baseline of 4. The description doesn't add parameter details (there are none), but it does provide context about the operation's scope, which is sufficient.

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 a specific verb ('Reload'), resource ('Oxidized node list'), and source ('from its source (router.db, SQL, HTTP, ...)'). It distinguishes itself from the per-node reload by explicitly noting that per-node reload replaces the entire list and is deliberately not offered. This clearly differentiates from siblings like list_nodes or trigger_node_backup.

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: 'Use after devices were added, removed or changed in the source' and explains the benefit ('without waiting for its next refresh'). It also notes that it always reloads every node, implying it is not suitable for single-node reloads, and explains why per-node reload is not available. It does not explicitly list alternative tools, but the per-node caveat serves as an implicit exclusion.

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 flag read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond those flags: it explains the two-phase search process, that matching lines come with line numbers, that patterns must be valid in both Ruby and Python regex, and that multi-line patterns will find nodes but produce no matching lines. 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 well-structured: a one-sentence summary comes first, followed by the operational flow, concrete usage examples, and then an important cross-language regex caveat. Every sentence earns its place without unnecessary padding.

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 is complete for an agent to use this tool correctly. It explains the search behavior, the regex constraint, the line-matching limitation, and when to reach for the tool. The input schema fully documents all seven parameters, and an output schema exists, so return-value details are not the description's responsibility.

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 parameter-level value by warning that the pattern must be valid in both Ruby and Python regex and that lines are matched one at a time, which directly affects how the pattern parameter should be authored. This goes beyond the schema's short parameter 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?

Purpose is stated with a specific verb and resource: "Search the latest configurations of all nodes for a pattern." It clarifies the two-step process (find matching nodes, then fetch and return matching lines), distinguishing it from sibling tools like get_node_config, which fetches a single config, or list_nodes, which enumerates nodes.

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 concrete, recognizable use cases: "which devices still have telnet enabled" and "where is VLAN 42 configured". This tells an agent when this tool is appropriate, though it does not explicitly contrast it with alternatives or state when not 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?

Annotations only indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds crucial behavioral context beyond those: the node moves to the head of the queue, the backup runs asynchronously, and name/IP matching is group-less with a uniqueness requirement. It also explains the consequence of a changed configuration (a new version appears), giving the agent a full picture of the tool's runtime 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?

The description is compact and front-loaded with the primary purpose. The first sentence states the action immediately, followed by two sentences that earn their place by covering async behavior, follow-up steps, and a critical uniqueness constraint. No fluff 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?

For a tool with three parameters, an output schema, and annotations, the description covers everything an agent needs to invoke it correctly: what happens (queued async backup), how to verify the result (get_node, list_node_versions), and a key constraint (unique node names). The output schema handles return-value details, so no critical context 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?

Schema description coverage is 100%, with clear descriptions for node, user, and message. The tool description adds no additional meaning about parameters beyond what the schema already states. Since the schema fully documents each parameter, the baseline of 3 is appropriate.

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: 'Queue an immediate configuration backup of a node.' It clearly distinguishes this from sibling retrieval tools like get_node_config or list_node_versions by focusing on triggering a backup rather than reading data. The follow-up references to get_node and list_node_versions further disambiguate its role.

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 clear context for when to use the tool: when an immediate backup is needed. It also provides post-invocation guidance ('Check get_node afterwards... list_node_versions for a new version') and a uniqueness prerequisite. It does not explicitly state when not to use it or name direct alternatives, but the usage context is strong enough for an agent to select it correctly.

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