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

With no annotations provided, the description fully carries the transparency burden. It discloses the write behavior (records a real task + receipt), the provenance label, the refresh-only behavior after 14 days, and explicitly states 'proving cannot be farmed.' It also details the two auth mechanisms and their effects, providing rich behavioral context beyond any structured annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: it front-loads the core action and outcome, then covers re-proving behavior, auth methods, and return values. No fluff or repetition; the structure flows from purpose to usage to details.

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

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

Given the tool's complexity, the description covers the workflow (proving rung, liveness window), auth paths, return object, and even the 'cannot be farmed' constraint. It lacks explicit mention of the required agent_id and does not state 'you must call guild_prove first', though it implies it via the challenge reference. Overall, it is quite complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains api_key ('presenting your api_key IS the proof') and signature (hex ed25519 over the JCS-canonicalized challenge), adding meaning beyond the schema. However, the required agent_id parameter is never mentioned, leaving a gap in semantic 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's purpose: 'Complete the proving rung' and details the outcome (records a real task + receipt, advances to journey stage 2). It distinguishes itself from sibling tools by referencing the 'challenge' from guild_prove and describing re-proving behavior, making its unique role evident.

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 on when to use the tool: first success versus re-proving after the 14-day liveness window. It also gives agent-specific guidance (custodial vs self-sovereign) and implies a prerequisite by referencing the challenge object from guild_prove. However, it does not explicitly name alternatives or when not to use, stopping short of full exclusion guidance.

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