server

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds no behavioral context beyond stating it is an attestation. It does not contradict annotations but adds minimal value.

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 waste, 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?

Adequate for a simple tool, but lacks details on idempotency, write nature, and what happens on duplicate or missing routes. No 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?

Schema description coverage is only 33% (only note described). The tool description does not mention any parameters, so it fails to compensate for the low 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 the tool reports route outcome (success/failure) and distinguishes from siblings waymark_contribute and waymark_query by its specific action of attesting.

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 says 'always attest after using a route', providing clear when-to-use guidance, though it doesn't explicitly state when not to use or name 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?

Given no helpful annotations (all false), the description adds value by specifying to submit only sanitized procedure, never credentials/personal data, and requiring an API key. It does not cover mutation effects or return format, but the core behavioral constraints are clear.

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 with no wasted words: purpose, data constraints, and auth requirement are front-loaded. Every sentence adds value.

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

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

For a 6-parameter tool with no output schema, the description covers purpose, data to submit, what to avoid, and auth. Missing explanation of return value or confirmation, but the tool is simple enough that this 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?

Schema description coverage is 100%, so baseline is 3. The description emphasizes sanitization and API key requirement, adding context beyond schema descriptions, but does not detail each parameter's usage.

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

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

The description clearly states the tool contributes a sanitized procedure (route) after completing a task, and the title 'Contribute a route to the map' reinforces this. It distinguishes from siblings (waymark_attest, waymark_query) by focusing on contribution, not attestation or querying.

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 use after completing a task but does not explicitly state when not to use it or compare with sibling tools. No exclusions or alternatives are given, leaving usage judgment to the agent.

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

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

Annotations already mark the tool as read-only, so the description need not reiterate that. It adds value by describing the return content (step sequences, gotchas, success statistics). However, it does not disclose any potential behavioral nuances beyond what the 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?

The description is two sentences, clearly structured: first sentence states when to use, second explains what is returned and how to use the result. No wasted words; all information is relevant and 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 no output schema, the description adequately explains return values (step sequences, gotchas, statistics) and mentions the 'route_id'. However, it could provide slightly more detail on the structure of the returned data, but overall it is sufficient for a tool of this 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 coverage is 67%, with 'task' and 'domain' having descriptions. The description does not add further meaning to the parameters beyond the schema. Since schema coverage is high, a 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's purpose: query Waymark for pre-existing routes before non-trivial tasks. It specifies the verb 'query', the resource 'Waymark route map', and distinguishes from siblings by indicating that waymark_attest is used after completion.

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

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

The description explicitly advises using this tool before non-trivial tasks and directs the agent to use waymark_attest with the returned route_id afterward. While it does not list when not to use this tool, the context and sibling tool names implicitly guide appropriate usage.

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 basic behavioral hints, but the description adds value by noting the key is returned once (non-recoverable) and must be stored. 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?

Two sentences, no wasted words, front-loaded with the key action and purpose. Each sentence adds essential information.

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

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

For a simple registration tool with one parameter and no output schema, the description fully covers what the agent needs: purpose, usage caveats, and parameter hint. 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?

The schema has 100% coverage with a description for 'handle'. The tool description adds an example and explains its purpose, enhancing understanding beyond the schema alone.

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: obtaining a free contributor API key for use with waymark_contribute. It distinguishes itself from sibling tools by explicitly linking to the contribution workflow.

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 usage context: the key is returned once, must be stored, and one handle per agent/org. It does not explicitly state when not to use, but the purpose is self-evident for a registration tool.

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