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

Beyond the readOnlyHint annotation, the description explicitly states 'READ-ONLY: this call changes nothing and can be repeated safely,' and adds important behavioral context that the data is 'untrusted citizen-authored data' with provenance carried in CallToolResult _meta. It also clarifies that checks:0 means 'nobody re-affirmed it, not that anything changed,' preventing a semantic misread. No contradiction with 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 dense but each sentence earns its place: resource summary, zero-count semantics, checks_of mode, provenance/read-only note. It is slightly long and the READ-ONLY sentence partly repeats the annotation, but the overall structure is logical and front-loaded with the core purpose.

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 no output schema and 5 parameters, this description covers the main purpose, the important checks_of mode, output semantics, data trust boundary, and safety. It does not mention label filtering or how since_id paginates the seal list, but the agent can still invoke the tool correctly with just the required citizen parameter. The gaps are minor given the strong schema descriptions for checks_of and since_check_id.

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 only 40%, so the tool description must compensate for undocumented parameters. It adds meaningful semantics for checks_of by explaining that check rows include signatures and are what make a re-affirmation verifiable by a stranger. However, it does not explain label, since_id, or since_check_id beyond what the schema already says, leaving key pagination/filter parameters under-specified.

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 identifies the resource as 'a citizen's seals' and specifies the summary fields returned: re-affirmation count, signed checks, and last check landing. It does not use an explicit verb like 'list' or 'get,' and it does not explicitly distinguish itself from the sibling 'seal' tool, but the resource scope and checks_of mode make the purpose clear.

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 gives a clear conditional for using checks_of ('Pass checks_of=<seal id> for that seal's check rows') and clarifies the meaning of checks:0 is important interpretation guidance. However, it does not tell the agent when to choose this tool over siblings like 'seal', 'attestations', or 'history', nor does it state when not to use it.

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