verify_chain

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

With no annotations, the description carries the full burden and does so: it declares read-only behavior explicitly ('never edits, retracts or supersedes — a failing row is for a human to act on'), defines the success signal ('`green` is true only when nothing failed'), and pre-empts a false positive ('not enumerated by the walk but its TriG resolves' is fine, not a warning). It also bounds the analysis scope (neighbour chains 'never judged'), which is exactly the kind of nuance an agent could not infer.

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?

It is front-loaded with purpose and trigger before any detail, and the bulleted check list keeps a long specification scannable. It is on the verbose side — the CiTO paragraph and the walk/neighbours caveats are dense — but almost every sentence conveys a distinct rule an agent would otherwise get wrong.

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 complex, domain-specific verification tool with no annotations and no output schema, the description covers checks, success criteria, false-positive tolerance, and mode semantics. The remaining gaps are the undocumented `repo_url` parameter and only partial disclosure of the return shape beyond `green` and `neighbours`.

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 coverage is 0% and the schema declares no enums, so the description must supply semantics — and it does for `mode`, enumerating auto/replication/reproduction/new_research and explaining precisely what each changes ('It changes only what is REQUIRED'). `published_path` is described by example (ledger file or the directory holding one). `repo_url` is never mentioned, leaving one of three parameters unexplained.

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 opening sentence gives a specific verb+resource ('Verify a published FORRT chain') and the 'published' qualifier implicitly separates it from the sibling draft validators (validate_chain_draft, validate_draft). The bulleted 'What it checks' list makes the scope concrete enough that an agent can tell it apart from every other sibling.

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?

It states the trigger ('Run this before announcing it anywhere') and the expected input shape ('Point it at a nanopubs/PUBLISHED.md ledger (or the directory holding one)'). It also tells the agent how to use `mode` ('pass one explicitly only to make the wording match your study'). It stops short of explicitly naming the alternative sibling tools (validate_chain_draft / validate_chain), so the routing is inferred rather than stated.

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