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

The description goes well beyond the annotations by disclosing that the live check is an observation, not semantic truth; that it does not recompute content dates, record counts, or shape fingerprints; that results are ephemeral and do not update published health artifacts; and that an unreachable or not_verifiable verdict only means the live comparison could not establish a match. It also discloses rate limits (roughly one request per second with a small burst) and that DataPulse is read-only and requires no API key. This is rich behavioral context that complements the readOnlyHint and idempotentHint annotations without contradicting them.

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 well-structured, front-loading the primary use case and verdict types before moving to exclusions and rate-limit details. It is longer than strictly necessary, but every sentence carries meaningful information: the observation caveat, ephemeral results, workflow sequence, exclusions, and rate limits all earn their place. The only minor issue is that the final sentence packs several distinct facts (unreachable verdict meaning, ephemerality, read-only, no API key, rate limit) into one long sentence, which slightly reduces scannability.

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 tool with one parameter, a rich output schema, and comprehensive annotations, the description is complete. It covers what the tool does, when to use it, what it does not do, what the verdicts mean, rate limits, authentication requirements, and how it fits into a broader audit workflow. An agent has everything needed to select and invoke this tool correctly without opening the schema or output schema.

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 already covers the single parameter dataset_id with 100% coverage, including an example and a note about browser-dependent sources returning not_verifiable. The description adds context by explaining the parameter is a stable direct-access dataset slug returned by search_datasets, which helps the agent understand where the value comes from. Since schema coverage is 100%, the baseline is 3, and the description's added context about the slug's origin and the browser-dependent caveat justifies a 4.

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 performs a rate-limited live-vs-published comparison for a direct-access dataset and returns a verdict. It distinguishes itself from siblings by explicitly naming verify_dataset and verify_attestation as alternatives for different purposes, and the title 'Live-check Published Transport Evidence' reinforces the specific verb and resource.

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 ('Use when a fresh, rate-limited live-vs-published comparison is needed'), gives a concrete example ('after asking whether a government dataset is reachable now'), and explicitly states what not to use it for ('do not use it for published receipt integrity or signed-attestation verification—use verify_dataset or verify_attestation instead'). It also outlines a deep-audit workflow sequence, which is strong usage guidance.

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