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

Despite annotations indicating destructive behavior, the description adds significant context: it categorizes commands by risk tier (Read, Benign, Config, Sensitive, Destructive), explains the dryRun flag for previewing effects, and provides specific behavioral notes (e.g., firmware rejecting backwards clocks, key exclusion for security).

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 front-loaded with a clear summary and then structured into categorized command blocks. While lengthy, every sentence serves to document a command or parameter, making it efficient for its purpose. Could be further optimized but remains functional.

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 (many commands, nested parameters, output schema), the description covers all aspects: command catalog, parameter details, dryRun behavior, risk tiers, and error handling (unknown command returns valid list). The output schema is separate, so completeness is high.

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 has low coverage (25%), but the description fully compensates by enumerating every valid command and its sub-parameters with detailed syntax and constraints. This adds immense meaning beyond the minimal schema definitions.

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 purpose: 'Run one enumerated admin command against a node.' It specifies the resource (admin commands) and the action (run against a node). The extensive list of commands distinguishes this tool from sibling tools that target specific 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?

The description provides context for when to use the tool (to run admin commands) but does not explicitly exclude alternatives or guide when to use sibling tools instead of this general tool. The listing of commands implies coverage, but no direct guidance is given.

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 indicate non-read-only, non-destructive, non-idempotent behavior. The description adds value by noting 'Costs airtime; flood propagates mesh-wide', which are key behavioral traits not captured by annotations. However, it does not detail all edge cases (e.g., behavior on invalid nodes).

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 mode selection. Every sentence adds value: purpose, node usage, cost/propagation. No wasted words, clearly structured.

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 (3 parameters, no required fields, enum, output schema exists), the description covers the essential behavioral aspects (mode, node targets, cost). It lacks explanation of dryRun output or error handling, but the output schema likely fills 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 coverage is 100%, so baseline is 3. The description reinforces the meaning of 'mode' and 'node' (e.g., 'omit to target home') but does not add significant extra semantic detail beyond what the schema provides for all parameters, especially 'dryRun'.

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 ('Send an advert') and the resource ('from a node'). It distinguishes between flood and zerohop modes and gives a specific equivalent to the admin command, helping the agent understand its purpose among sibling 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 explains when to use each mode ('flood' vs 'zerohop') and how to target the home node by omitting the 'node' parameter. It warns about airtime costs and mesh-wide propagation, but does not explicitly exclude alternative tools or provide 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?

Annotations already declare destructiveHint=true. Description adds minor context about addressing but no new behavioral traits 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?

Two focused sentences with no redundancy. Action and key constraint 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?

With full schema coverage, annotations, and output schema present, the description is sufficient for the tool's complexity.

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 has 100% coverage; description does not add meaning beyond what the schema provides for index and name.

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 'Remove a channel slot' with specific addressing by index or name. Distinguishes from related tools like set_channel and the listing resource.

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 context to list channels first via meshcore://channels, implying prerequisite. Does not explicitly state when not to use or compare to other mutation tools.

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 that the tool sends a broadcast request that populates a neighbor list (a write operation), consistent with readOnlyHint=false and destructiveHint=false. It adds context beyond annotations by explaining the side effect and how to retrieve results, but does not cover failure modes or rate limits.

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 concise sentences with no filler. The primary action is stated first, followed by outcome and alternative invocation. Every sentence provides 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?

The description covers the core action and result, and references sibling tools for reading neighbors. With an output schema present, it does not need to detail return values. Minor gaps: no mention of error scenarios or idempotency, but adequate for a simple 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% with descriptions for both parameters. The description repeats that 'node' is required and references the admin command, but adds minimal new semantic detail beyond the schema. 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 uses a specific verb ('broadcast') and resource ('node-discovery request'), clearly indicating the action. It distinguishes from sibling tools like 'admin' by stating it is equivalent to 'admin <node> discover-neighbors', and references 'get_node_neighbors' for reading results.

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 mentions that the tool is equivalent to an admin command and requires a node, but does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives like 'admin' or other discovery tools. It lacks exclusions or context for 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?

Adds context beyond annotations: output format (hex bytes), suitability for import_contact. Annotations already indicate read-only and idempotent, so description complements well.

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, front-loaded with purpose, no unnecessary 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 output schema exists, description covers all needed aspects: purpose, parameter behavior, and use case for off-mesh identity sharing.

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 100% and description adds value by explaining the behavior when parameter is omitted, going beyond 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?

Clearly states it returns advert-packet bytes for a contact, distinguishes from sibling import_contact by specifying the output format and usage.

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 on omitting target to export home node's advert. Does not explicitly exclude alternatives but implies use cases.

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 idempotent. Description adds value by explaining the fallback behavior and clarifying that the end state is the same whether an entry existed or not, beyond what annotations 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?

Three concise sentences, front-loaded with the core action, followed by useful context and a note on destructiveness. 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?

With one parameter, annotations covering safety, and the description covering fallback, idempotency behavior, and the return flag 'removed', the tool is fully documented for an agent to use 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 describes 'node' as contact name or hex public-key prefix. Description uses the parameter but does not add new semantic details 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?

Clearly states 'Remove the server's stored login password for `node`' with a specific verb and resource. Distinguishes from sibling 'set_credential' by describing the opposite action and fallback behavior.

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?

Explains that after removal, admin/health calls fall back to default credentials, giving context on when to use. Mentions return value nuance. Lacks explicit when-not or alternative tools, but context 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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the description adds minimal behavioral context beyond equating it to an admin command. No 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?

Two sentences with no wasted words: first sentence states purpose, second provides usage guidance. Front-loaded and efficient.

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 rich annotations and an output schema, the description covers purpose, usage alternatives, and parameter requirement adequately without missing critical 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?

Schema coverage is 100%, and the description repeats the schema's note about node not targeting home. No additional meaning added beyond schema, meeting baseline for high coverage.

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 it reads a remote repeater's hardware board/model identifier, distinguishing it from siblings by noting the alternative for home node via get_node_health().

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 says node is required, and instructs to use get_node_health() for the home node as a better alternative, providing clear 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable context about the output format, the requirement for a remote node, and the equivalence to an admin command. No contradictions.

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 with zero waste. The first sentence states the core function and output format, the second provides the alternative for home node. Front-loaded and efficient.

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?

With full schema coverage, rich annotations, and an output schema present, the description completes the picture by explaining the remote-only constraint, output format, and alternative usage. No 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?

Schema coverage is 100%, so baseline is 3. The description adds extra semantic info for the required 'node' parameter, explaining it cannot target the home node due to firmware limitations. This provides meaning 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 clearly states it reads a remote repeater's current device clock, specifies the output format (HH:MM - D/M/Y UTC), and distinguishes from the sibling tool get_node_health for the home node. This provides a specific verb+resource with clear differentiation.

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 when to use this tool (for remote nodes) and when not to (for home node, use get_node_health). Also notes it is equivalent to an admin command, providing clear context and 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?

Annotations already indicate read-only and idempotent behavior. The description adds that the reply is a single line of text and mentions the intentional exclusion of 'prv.key' for security, which is beyond annotation coverage.

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 consists of two focused sentences with no redundancy. Each sentence serves a clear purpose: stating the function and providing an alternative use case.

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 (not shown), the description adequately covers purpose, usage, and a behavioral note. A minor gap is the lack of explicit return value structure, but output schema fills that.

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% with descriptions for all parameters. The description adds value by listing example keys and noting the 'prv.key' exclusion, but does not significantly expand beyond 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 reads a specific config value by key from a remote node, with examples. It distinguishes from sibling get_node_health which covers structured fields for the home 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?

The description explicitly notes the required 'node' parameter and directs users to get_node_health for home node config. However, it does not provide exhaustive guidance on when to avoid 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?

Annotations already provide readOnly, destructive, idempotent, and openWorld hints. The description adds valuable context about logging into remote nodes, which implies authentication needs. Does not mention rate limits or error conditions, but rated highly due to annotation coverage.

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 concise and purposeful. The key usage guideline is front-loaded, and no extraneous information is present, making it easy to scan.

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?

With an output schema present, no need to describe return values. The description covers purpose, parameter usage, and behavioral context comprehensively for a read-only health snapshot 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 covers 100% with a clear description of the 'node' parameter. The description adds nuance: omission for home node, and provides intent for remote nodes, enhancing understanding beyond the schema 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?

Clearly states 'consolidated health snapshot' and lists specific data categories (identity, radio, battery, uptime/queue, packet/radio stats). Distinguishes from siblings by focusing on a comprehensive health overview rather than specific details.

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 tells when to omit the parameter (home node) and when to provide it (remote repeater), with instructions on inputs. Provides context on the remote behavior (logs in and reads status), helping decide between this and other tools.

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, destructiveHint, idempotentHint, and openWorldHint. Description adds useful behavioral context: returns up to 8 neighbors in a specific format, mentions the companion firmware limitation ('can't target home'), and notes the data source. 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?

Description is concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, context, equivalent command, pairing with sibling. No redundant or vague phrasing.

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 (two parameters, annotations cover safety, output schema exists), the description is complete. It explains the return format, pairing with sibling, and data source. No missing critical 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?

Schema coverage is 100% with descriptions for both parameters. Description adds minimal extra context for `node` (companion firmware limitation) but does not address `dryRun`. Baseline of 3 is appropriate as 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?

Description clearly states 'List a remote repeater's recent neighbours (up to 8)' with a specific verb and resource. It distinguishes from sibling `discover_neighbors` by mentioning it pairs with an active probe. Also notes equivalence to `admin <node> neighbors`, reinforcing the 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?

Description provides clear context: it is the H15 topology data source and pairs with `discover_neighbors(node)` for fresh data. It implicitly advises when to use each tool. However, no explicit when-not-to-use statements are given.

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, destructiveHint, idempotentHint. Description adds context: it's equivalent to a CLI command, only works on repeater firmware, and returns version+date. Does not contradict 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, no wasted words. Front-loaded with purpose, then equivalence, then usage guidance. Ideal length.

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?

Output schema exists (not shown but indicated), so return format is covered. Description adds what is returned (firmware version + build date string). With annotations and schema, the description is 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 covers both parameters with descriptions. Description adds rationale: node is required because command isn't implemented on companion firmware, so can't target home. This adds meaning beyond 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 it reads a remote repeater's firmware version and build date. It distinguishes from sibling get_node_health, which returns structured firmware info for the home 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?

Explicitly states when to use: for remote repeaters (only repeater firmware implements the ver CLI). Explicitly states when not to use: for home node, use get_node_health() instead.

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, idempotent, and non-destructive behavior. The description adds context about ordering (oldest→newest), tagging (provenance), and parameter behavior (relative vs wall-clock).

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, front-loaded with the main purpose, followed by parameter guidance. Every sentence provides essential 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 tool with one optional parameter, rich annotations, and an output schema, the description covers purpose, usage, and parameter behavior completely. No missing 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?

Schema coverage is 100%, so parameter 'since' is documented. The description adds value by clarifying portable form (relative duration) and noting that ISO-8601 and epoch-ms are also accepted but wall-clock instants.

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 retrieves recent live mesh traffic from a rolling buffer, ordered oldest to newest, tagged with provenance. It distinguishes from sibling tools, which cover different actions like sending messages, admin, or other node info.

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 the 'since' parameter, including preferred relative durations and alternative formats. It doesn't explicitly exclude scenarios, but the context is clear for a read operation; alternatives are not needed given sibling diversity.

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 idempotentHint=true and destructiveHint=false are present; description adds that the contact appears in survey_mesh and contacts resource after, providing useful 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?

Two sentences, front-loaded with the action, no fluff. 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?

With one parameter, annotations, and no need to explain return values due to output schema, the description is complete and sufficient for an agent to use.

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% with a good description. The description adds context about the source of the hex bytes (export_contact output), enhancing 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 tool adds a contact from advert-packet bytes and specifies the source. It distinguishes from siblings like export_contact (opposite direction).

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 explains when to use (having advert-packet bytes from export_contact, QR scan, etc.) but doesn't explicitly mention when not to use or other methods. Clear context is provided.

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 key behaviors beyond annotations: node unreachable for 30-60s, session ends, and equivalence to admin command. Combines with annotations (destructiveHint=true) to give a full picture.

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?

Very concise: two sentences plus a warning symbol. Front-loaded with the core action and target. No unnecessary 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 presence of an output schema and the tool's low complexity (2 optional params), the description fully covers usage, behavior, and effects. No gaps identified.

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 description does not add new information beyond schema for parameters. The description repeats the schema's note on omitting node but does not elaborate on dryRun.

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 ('Reboot a node'), specifies the target types (home companion or remote repeater), and distinguishes behavior when node parameter is omitted. It effectively differentiates from sibling tools by being the top-level reboot command.

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 guidance on when to omit the node parameter and notes equivalence to an admin command. However, does not explicitly discuss when not to use the tool or compare with sibling alternatives like 'admin'.

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-read-only behavior. The description adds important context: the operation is local-only, the contact may reappear if auto-add is enabled, and suggests a mitigation. This goes beyond the annotations by explaining side effects and dependencies.

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 with three front-loaded sentences: purpose, scope, and usage note. 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?

For a simple tool with one parameter and clear annotations, the description covers essential behavioral and usage context. The lack of output schema content is not a major gap given it exists elsewhere. The description sufficiently informs the agent about local scope and auto-add interaction.

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% with a clear description of the 'target' parameter. The tool description does not add new information about the parameter beyond what the schema provides, so a 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 states the tool removes a contact from the local roster ('Drop a contact from the local node's roster'), with a specific verb and resource. It also distinguishes from siblings by noting it is local-only, not affecting other nodes, which differentiates it from distributed 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?

The description provides guidance on when to use and how to achieve a sticky removal by combining with set_auto_add_contacts. It explains the reappearance risk under auto-add mode. However, it does not explicitly state alternatives for removing contacts from all nodes, which may be implied by local-only.

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 idempotentHint=true. The description adds behavioral context by explaining the effect (clears cache, next send re-discovers route) and the consequence (no direct sends affected until next one). This adds value 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?

Three sentences, no wasted words. First sentence states action, second explains consequence, third gives usage scenario. Perfectly concise and structured.

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, idempotent, non-destructive) and the presence of an output schema, the description covers all necessary aspects: what, how, when, and why. No 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?

With schema coverage at 100%, the description does not add extra meaning beyond the schema's parameter description. The schema already explains 'contact name or hex public-key prefix', so 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 clearly states the tool clears a local cached path, with specific verb 'clear the local cached forwarding path'. However, it does not explicitly distinguish itself from sibling tools like `set_contact_path` or `trace_path`, though the action is unique enough.

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 this tool: when a known path has gone stale, direct sends are failing or slower. It does not explicitly state when not to use it or mention alternatives, but the usage scenario is well-explained.

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 non-idempotent behavior and confirmation scope beyond annotations (readOnlyHint=false, idempotentHint=false), with no contradictions.

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 with purpose, but the sentences are somewhat dense; slightly better structure would merit a 5.

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 presence of an output schema, the description adequately covers input semantics, idempotency, and confirmation details without needing to explain return values.

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 description largely echoes schema descriptions without adding new semantic value beyond the structured data.

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 'Transmit a text message' and specifies target formats (contact or channel), making the tool's purpose distinct from siblings like broadcast_advert.

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 explains how to use the tool, including confirm behavior and channel limitations, but does not explicitly state when to avoid using it or compare with 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?

Annotations already indicate idempotence and non-destructiveness. The description adds context about the companion default ('autoAdd: true') and explains the effect of each mode. No contradictions.

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 with no redundant information. Every word earns its place, and the structure is 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 simple toggle nature, low parameter count, and presence of an output schema, the description is complete. It could briefly mention the return value, but that is covered by the output schema.

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 describes the boolean parameter with 100% coverage. The description adds value by specifying the companion default and suggesting manual mode's complementary use with 'remove_contact'.

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 title 'Toggle auto-add for new contacts' and description clearly specify the verb 'Set' and resource (auto-add behavior for new contacts). It distinguishes itself from siblings like 'remove_contact' and 'import_contact' by mentioning their interplay.

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 a usage hint by pairing manual mode with 'remove_contact' for curated contact lists. However, it does not explicitly state when not to use the tool or list alternatives beyond 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?

Annotations indicate idempotentHint=true, and the description adds behavioral context: it explains that omitting index uses next free slot (so plain add won't overwrite), and it returns the channel's key. 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 with three sentences, each adding value: first sets purpose, second gives parameter guidance, third covers return value and alternative listing. 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 (3 parameters, 1 required, output schema exists), the description covers purpose, parameter behavior, return value, and alternative listing method. It is complete for an AI agent to select and 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?

Schema coverage is 100%, baseline 3. Description adds semantics by explaining the effect of omitting 'secret' (generates random private channel) and 'index' (uses next free slot), 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 configures a channel slot on the connected node, with specific verb 'configure' and resource 'channel slot'. It distinguishes from siblings like 'delete_channel' and 'send_message' by focusing on channel configuration.

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 guidance on when to omit 'secret' (to generate a random private channel) and when to omit 'index' (to use next free slot), and mentions alternative listing via 'meshcore://channels'. However, it does not explicitly state when not to use this tool versus other tools.

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 idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds that setting pathHex to empty string marks contact as direct, and path is up to 64 bytes, which is useful behavioral context beyond annotations. No contradictions.

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, front-loaded with the core purpose, no filler. Every sentence adds essential information: purpose, usage guidance, and parameter hint.

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 only two parameters, full schema coverage, and an output schema (exists), the description provides sufficient context including max length, pairing with a sibling tool, and when to use. No 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?

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the meaning of empty pathHex ('mark as direct') and that pathHex represents repeater path-hash bytes, which clarifies the schema's pattern.

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 'Set' and resource 'explicit forwarding path to a contact', distinguishing it from siblings like 'trace_path' which discovers paths, and 'reset_path' which likely clears paths. It specifies that it overrides automatic path discovery, making its 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 explicitly says 'Advanced: only when you want to override automatic path discovery', giving clear guidance on when to use. It also recommends pairing with 'trace_path' first, but does not explicitly list alternatives or when not to use, which is a minor 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?

Discloses overwrite behavior, storage details (file, permissions, no echo), guest vs admin tiers, and failure recovery (ERR reply), adding context beyond annotations which already convey idempotency.

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?

Well-structured and front-loaded, but slightly verbose with extra detail on admin/guest; still every sentence serves a purpose.

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?

Thoroughly covers behavior, constraints, edge cases (typo, ERR recovery), and interplay with admin/get_node_health, fully equipping the agent.

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?

Adds meaning beyond schema: node must be in contact list, password max 256 chars, explains admin/guest implications, which the schema's descriptions only hint at.

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 explicitly states the tool persists a password for admin and health calls, clearly distinguishing it from siblings like forget_credential and set-admin-password.

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 (out-of-band password learning) and when-not (typo rejection, not node's own password), with clear differentiation from related commands.

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 this tool as idempotent and non-destructive. The description adds the home node behavior and CLI equivalent, but doesn't provide additional behavioral context beyond what annotations cover.

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 cover purpose, usage, and equivalent command with no wasted words. Information is front-loaded and each 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?

The tool is simple, with 4 parameters and an output schema. The description covers the core purpose and key usage hint. It is nearly complete, though it could mention lat/lon bounds or validation.

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?

With 100% schema coverage, the baseline is 3. The description adds value by explaining the 'node' parameter's default behavior (omit for home) and clarifying that lat/lon are in decimal degrees, going 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 clearly states the verb 'Set' and resource 'node's advertised lat/lon', adding specificity about decimal degrees and distinguishing it from sibling tools like set_tx_power or set_contact_path.

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 usage guidance by noting that omitting the 'node' parameter targets the home node. It also gives an equivalent CLI command, but does not explicitly mention when not to use 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?

Annotations already indicate idempotent, non-destructive, non-read-only. Description adds the important behavioral constraint 'Max 32 bytes (24 if a location is set)', which goes beyond annotation details. No contradictions.

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, no fluff. Purpose stated first, then usage nuance, then critical constraint. Every sentence serves a purpose.

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 (3 params, no optional, output schema exists), the description covers purpose, key usage (omit node), and parameter constraint. Does not discuss output, but that's outside scope due to output schema. Could mention error handling for invalid names, but 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%, baseline 3. Description adds value: clarifies name byte limit with location caveat, and repeats the omission rule for node, reinforcing the schema. This extra context justifies 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?

Description clearly states 'Rename a node's advertised mesh name' with specific verb and resource. It distinguishes from siblings like set_node_location by focusing on name. The note about omitting node for home adds precision.

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?

Description explains when to omit the node parameter to target home, and provides an admin command equivalent for context. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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 critical behavioral info beyond annotations: delayed effect after reboot and potential node disconnection if params don't match mesh. Annotations indicate idempotent and non-destructive, but description discloses side effects.

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 plus a warning. Front-loaded with main action. No extraneous 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?

With output schema present, no need to describe return values. Covers purpose, node targeting, and key behavioral warning. Schema fully documents parameters. Complete for the tool's complexity.

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 description adds little beyond listing parameter names. Baseline 3 as schema does the heavy lifting; description does not provide new semantic 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?

Clearly states the action (set) and resource (radio parameters on a node). Specific about parameters (frequency, bandwidth, spreading factor, coding rate). Distinguishes from sibling tools like set_channel, set_node_name, etc., which deal with different aspects.

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 guidance on omitting `node` for home and warns about reboot and network drop-off. Does not explicitly mention when not to use or compare to alternatives, but the warning is valuable 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?

Discloses important behaviors beyond annotations: the PA stage can amplify the configured dBm, implying the actual output may differ. Annotations already indicate idempotency, so no contradiction. Adds context about destructive potential (legal issues) despite destructiveHint=false.

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 plus a warning emoji. Every word adds value. Front-loaded with action, then parameter details, then critical caution. Excellent conciseness.

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, parameters, default behavior, and a critical safety warning. Output schema exists and need not be described. Very complete for a simple setting 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 covers all params fully (100%). Description adds value by clarifying the default for 'node' and giving an admin command equivalent, which helps understanding. No ambiguity remains.

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 action (set radio transmit power) and resource (node). Specifies unit (dBm), distinguishes from siblings like set_radio by focusing on power only. Includes equivalent admin command for context.

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 default target (home node when omitted) and warns about legal/regional limits and PA stage. Could be improved by contrasting with set_radio's broader scope, but the guidance is clear and actionable.

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 non-read-only, non-destructive, non-idempotent, open-world behavior. The description adds the valuable detail 'Costs airtime', which discloses a cost not captured in annotations. No contradictions.

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, front-loaded with the primary action. Every word is essential; no redundancy or 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 simple schema (one parameter, fully described), annotations, and presence of an output schema, the description is nearly complete. It covers the purpose, effect, and a cost. It is slightly lacking in mentioning potential failure modes or prerequisites, but overall 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 coverage is 100% with the parameter 'target' described as 'contact name or hex public-key prefix'. The tool description does not add any additional meaning beyond what the schema provides, so 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 uses the specific verb 'broadcast' and clearly identifies the resource ('a contact's advert' across the mesh). It explains the effect (other nodes can route to the contact) and distinguishes from sibling tool 'broadcast_advert' by focusing on sharing a specific contact rather than the node's own advert.

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 the use case (propagating a contact's route) but does not explicitly state when to use this tool vs alternatives like 'broadcast_advert' or 'export_contact'. No 'when not to use' or prerequisite information is provided.

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 provide readOnlyHint, destructiveHint=false, idempotentHint, openWorldHint. Description adds that the tool returns specific fields (role, last-heard time), which is useful but does not reveal additional behavioral traits beyond annotations. No 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?

Single sentence that efficiently conveys purpose, output, and use case. No unnecessary words or repetition. Front-loaded with key action and result.

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 no parameters, rich annotations, and an output schema, the description is mostly complete. It explains the return content and purpose. Could be improved by mentioning ordering or whether contacts are sorted, but overall sufficient for an agent to understand usage.

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?

No parameters, so schema coverage is 100%. Baseline score is 4. Description compensates by explaining what the output includes (home node, contacts, role, last-heard time), which is the semantic meaning of the tool's result.

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 clearly states the tool lists the home node and every known contact with advertised role and last-heard time. The verb 'list' and resource are specific, and the purpose ('roster for spotting quiet or missing nodes') distinguishes it from sibling tools that focus on specific subsets like neighbors.

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?

No explicit guidance on when to use this tool vs alternatives like 'get_node_neighbors' or 'discover_neighbors'. The description implies usefulness for monitoring, but lacks direct comparison or exclusion 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?

Annotations already disclose read/write and non-destructive nature. Description adds 'No-op if already in sync' and mentions equivalence to admin sync-time, providing useful behavioral context 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 sentences cover purpose, default, equivalent command, no-op behavior, and alternative. Every sentence earns its place; 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 simplicity, presence of output schema, and full annotation coverage, the description is complete: it explains what the tool does, how to use it, default behavior, edge case (no-op), and a clear alternative for a different use case.

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% with clear descriptions for both parameters. Description reinforces the 'omit to target home' behavior for the node parameter but adds no new information 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?

States precise verb+resource: 'Set a node's clock to the controller's current time.' Clearly differentiates from 'admin' tool by mentioning the equivalent command and providing an alternative for explicit epoch.

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: 'Omit node to target home', 'No-op if already in sync', and gives an alternative tool call for explicit epoch: 'use admin <node> set-time { epochSecs } instead.'

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 timeout behavior ('A path that doesn't respond returns a timeout') but does not disclose whether the trace modifies state or requires specific permissions. Annotations are minimal (readOnlyHint: false, but no further 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 two sentences, directly stating the purpose and parameter usage without any fluff. It is front-loaded with the core function.

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 essential aspects: what the tool does, how to use parameters, and the timeout condition. Given that there is an output schema (not shown), not detailing the return structure is acceptable.

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 describes both parameters with examples (100% coverage). The description adds context about their usage (explicit path vs. known out-path for node), which helps differentiate the two options.

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 ('Trace a route through the mesh') and what it reports (SNR per hop). It distinguishes from sibling tools like reset_path or set_contact_path by focusing on tracing rather than modifying paths.

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 explains when to use the tool: to trace a route either by explicit path or by known node. It implies alternatives for path management but doesn't explicitly 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.