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

With no annotations at all, the description carries the full burden and discharges it: it discloses the $0.05 USDC on Solana price, that the service performs its own live fetch of the target under a fetch fence, that refused or unreachable targets are recorded not-observed rather than guessed, that the report is signed and deliberately carries no composite score, and that the result is not a security certification. It even enumerates what the payment includes and what is withheld from the disclosure list. Only latency, rate limits and idempotency are left unaddressed.

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?

Placeholder check — see corrected value below.

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 ten-parameter, no-output-schema, no-annotation tool, the description supplies the offer, the inputs, the report's anatomy and the scope limits, which is a lot. What remains thin is the intake/nesting detail (intakeModes, asDocs keyed by issuer) and any statement of failure or timing behaviour for the submission itself rather than the target fetch.

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 100%, so the baseline is 3. The description does add framing — grouping endpointUrl, statedCanonicalUrl and the published documents as the graded inputs, and clarifying that a self-reported capture is never merged with observed evidence — but it says nothing about card, manifest, intakeModes, declaredRevision or challengeObservation beyond what the schema already states.

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 states a specific verb and resource: it grades the published MCP auth surface of a server against all 38 checks of mcp-auth-surface/v1 and returns a signed report. That is far more specific than the name alone. It never names the neighbouring auth_surface_criteria or auth_surface_precheck tools, so the agent must infer the division of labour from context rather than being told.

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?

Usage is implied through the submission contract: you supply endpointUrl, statedCanonicalUrl and declaration documents and receive a graded report, and the self-reported capture is explicitly relegated to a labelled lower tier. Scope exclusions are also stated (declarations only, nothing behind authentication). What is missing is any explicit statement of when to reach for this versus auth_surface_precheck or auth_surface_criteria, and no prerequisites beyond payment are spelled out.

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