inspect_timestamp

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

The annotations already declare read-only, idempotent, non-destructive. The description adds crucial nuance beyond that: it clarifies that has_bitcoin_attestation is only a structural claim, not proof of Bitcoin backing, and states it makes no network calls. This transparently warns the agent about a misleading field, which is exactly the kind of behavioral disclosure expected.

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?

Three sentences, each carrying essential information with no filler. The primary action is front-loaded, the return-value list follows, and the critical caveat about attestation semantics is included. Everything earns its place.

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?

Despite having no output schema, the description enumerates the return metadata fields and explains the meaning of one key flag. It states the read-only nature and the absence of network calls. All information an agent needs to call this tool correctly and interpret results is present.

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 description covers the 'id' parameter 100% (UUID from the stamp record). The tool description does not add any extra parameter semantics, but the baseline for full schema coverage is 3, and no additional explanation is needed here.

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 starts with a specific verb and resource: 'Reads a stored proof file from disk' and lists exactly what metadata it returns (size, calendar attestations, Bitcoin attestations). It also distinguishes itself from verify_timestamp by framing its output as a 'structural check' vs. on-chain verification, so an agent can tell them apart.

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 explicitly directs the agent to use verify_timestamp before declaring a stamp confirmed, giving a clear when-not condition. It implies when to use inspect_timestamp (for metadata and structural checks) through the contrast, though it does not state an explicit 'use this when...' condition. The guidance is present and actionable, but slightly one-sided.

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