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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: it explains that a key nobody holds returns 'claim: null' rather than a not-found error, that the read signature cannot release the key, and that a placeholder signature can be used to retrieve the exact message to sign (details.expected). This goes beyond the annotations and helps the agent anticipate edge cases.

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 verbose and includes promotional content about the /feedback endpoint, which is unrelated to the tool's operation. The core purpose is front-loaded, but the additional marketing text about daily report analysis and no individual reply adds noise. While it is informative, it could be more concise without losing essential operational 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?

The description covers the key aspects an agent needs: the free nature, the wallet scoping, the null response for unheld keys, and the placeholder signature mechanism to obtain the exact signing message. It does not specify the full response structure for a held key (beyond implying a 'claim' field), but the absence of an output schema is mitigated by the description's explanation. This is sufficient for basic invocation.

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 provides descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds extra meaning for the 'signature' parameter by explaining the placeholder approach and the exact signature formats (EIP-191 and ed25519). It also clarifies that 'key' is scoped to the user's wallet. This added detail justifies a score above baseline.

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: checking who currently holds a specific key, scoped to the user's own wallet. It uses a specific verb ('holds') and resource ('key'), and distinguishes itself from sibling tools like claim_acquire and claim_release by emphasizing it is a read-only, free operation. The phrase 'scoped to YOUR wallet' also clarifies its limited scope.

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

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

The description provides context for when to use this tool: it is for checking your own key holdings and is free, explicitly noting that 'checking your own lock must not cost again'. It does not explicitly name alternative tools or state when not to use it, but the scope and read-only nature are clear. It could be improved by directly referencing siblings like claim_acquire for acquisition, but the guidance is adequate.

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