server

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

Annotations indicate a write operation (readOnlyHint=false), which aligns with the description. The description adds value by explaining consensus-based trust and the optional identity-attribution via api_key, beyond annotation information.

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 wasted words. Clearly states core action and important optional behavior.

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 4 parameters and no output schema, the description covers key aspects: when to use, optional parameters, and trust implications. Missing details on return values or error handling, but overall sufficiently complete for an attestation action.

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 50% schema coverage, the description adds meaning to parameters: route_id and outcome identify the route and result, note allows divergence explanation, and api_key is clarified as requiring validity for attribution. This goes beyond basic 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?

Description uses specific verb 'Report' and resource 'route outcome', clearly stating the tool's purpose. It distinguishes from siblings by focusing on attestation of route success/failure, which is unique among waymark 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?

Explicitly states 'always attest after using a route', providing clear when-to-use context. No direct exclusions or alternatives, but the sibling tools serve different purposes (contribute, query, register), making usage guidance adequate.

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 have readOnlyHint=false, idempotentHint=false, destructiveHint=false, indicating a non-idempotent write operation. Description confirms it's a submission, adds behavioral traits like sanitization requirement and need for API key. 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 purpose and constraints. Every word adds value: first sentence states action and rationale, second sentence adds restrictions and requirements. 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?

Covers what, when, and constraints (sanitization, API key). No output schema, but description doesn't need to explain return values. Could mention post-submission behavior (e.g., immediate success), but overall complete for agent 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?

Input schema has 100% description coverage with clear, concise parameter descriptions. Main description reinforces the 'sanitized' nature of steps and gotchas but doesn't add significant new semantics beyond what schema provides. 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?

Clearly states the verb 'contribute' and the resource 'sanitized procedure' for reuse by other agents. Distinguishes from sibling tools like waymark_query and waymark_attest by focusing on submission rather than retrieval or verification.

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 when to use: 'After completing a task'. Provides clear exclusions: 'never credentials, personal data, or payload contents'. Requires a contributor API key. Could explicitly contrast with siblings, but the context is sufficient.

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?

Description adds context beyond annotations: key is returned once (not idempotent), handle uniqueness (potential conflict). Annotations only provide readOnlyHint=false, destructiveHint=false, no idempotency hint. Description fills behavioral gaps.

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: first states purpose, second covers behavioral notes. Front-loaded, 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?

For a simple 1-param tool with no output schema, description covers purpose, key uniqueness, handle uniqueness. Could mention error cases (handle taken) but sufficiently complete for its 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 with a description for 'handle'. Description reinforces uniqueness ('first registration claims a handle') but adds minimal extra meaning beyond the schema's example and constraints.

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

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

The description clearly states the verb ('Get'), resource ('contributor API key'), and purpose ('so you can submit routes with waymark_contribute'). It distinguishes from sibling tools (waymark_attest, contribute, query) by being the registration tool.

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

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

Provides important usage notes: store the key (returned once), handles are unique, first registration claims a handle. Does not explicitly say when not to use, but context with sibling tools makes this clear.

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