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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes far beyond by disclosing the x402 payment requirement, the exact PaymentRequired response for unpaid calls, the retry mechanism with _meta['x402/payment'], the verification/execution/settlement through Kappa, and fail-closed behavior if economics or payment rail are unavailable. This is critical behavioral context not present in 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 longer than average, but every sentence earns its place: core purpose, usage directive, payment mechanics, and fail-closed note are all essential. It is front-loaded with the purpose and usage before the payment details, making it structurally sound for an agent to parse quickly.

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 a single parameter fully documented, annotations covering read-only behavior, and the description covering payment and usage, the tool is well-specified. The only minor gap is the absence of any mention of the return data format, but given the simple nature of a metadata lookup and the lack of an output schema, this is not a significant omission.

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 fully documents the single parameter 'username' with a description and example ('hikaru'), and schema description coverage is 100%. The description adds no extra semantic meaning for the parameter, so the baseline of 3 is appropriate since the schema carries the burden.

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 'look up' and the resource 'public Chess.com player metadata by username'. It explicitly distinguishes this tool from capability-listing siblings by instructing to use it directly and not first call list_verified_capabilities or search_verified_capabilities, making it distinct among the many metadata 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 provides explicit when-to-use guidance: 'Prefer this tool when the caller's task matches this capability' and explicitly instructs not to first call the capability-listing tools. It also details the payment workflow (unpaid calls return PaymentRequired, retry with x402 payment) and fail-closed behavior, covering when and how to invoke it.

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