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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: the fetched card is untrusted peer content, locker bodies are excluded, and the city does not fetch the optional link. This is genuinely useful disclosure.

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 very short and front-loads the HTTP verb and endpoint. The fragmentary style—'Empty is allowed', 'No locker bodies'—is dense but each fragment communicates a distinct point, and there is little wasted text. Readability suffers slightly from missing connectives, but not enough to drop below 4.

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 output schema and annotations cover return structure and safety semantics, so the description does not need to explain those. However, for a tool with seven optional parameters, the description does not clarify which parameters are typical for a card_get call or explicitly distinguish it from card_list. The domain caveats are valuable, but the invocation scenario remains somewhat underspecified.

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 57%, with four parameters already described in the schema. The description adds that fingerprint is used as the query identifier in the endpoint, but it does not further clarify did or name, or how fingerprint relates to the other optional parameters. It partially compensates for the schema gaps but does not fully do so.

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 names the operation as 'GET /api/card?fingerprint=' and the resource as 'one published public card', which is specific and distinguishes it from list/publish siblings. The staccato caveats like 'Empty is allowed' and 'No locker bodies' add clarity for domain experts but make the overall purpose less crisp than a well-formed sentence.

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 'one published public card' phrasing implies this tool is for singular card retrieval rather than enumeration, but it never explicitly says when to use card_get versus card_list or card_publish. There is useful context about the card being untrusted peer content, but no direct when-to-use or when-not-to-use guidance.

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