verify_quote

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

With no annotations, the description carries the full behavioral burden, and it delivers: it details the graded verdict tiers, the canonicalisation limits (never words, digits, or order), the not_found behavior with closest.text_in_pdf, and the evidence returned (page, character offsets, SHA-256). It even explains why extraction_tolerant matches are normal rather than warnings.

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 front-loaded with the core purpose, then organized into readable tiers and warnings. It is long but appropriately so for a tool with nuanced verdict semantics; each sentence adds decision-relevant information rather than padding.

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?

Given no output schema, the description fully explains the return values: verdict tiers, page, offsets, SHA-256, matched_text, and closest.text_in_pdf. It also covers failure interpretation and the risk of publishing a not_found quotation, making the tool safe to invoke without additional context.

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 0% and there are only two parameters, so the description must compensate. It does implicitly define pdf_path as the source PDF and quotation as the candidate text to search for, and it elaborates on how the quotation is matched. It doesn't spell out path formats or exact input constraints, but the semantic mapping is clear enough.

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: prove that a candidate quotation is really in a source PDF before it is published as verbatim. It is clear about what the tool does and its output, but it never explicitly distinguishes itself from siblings such as verify_chain or validate_draft, so it misses the full sibling-differentiation bar.

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 gives explicit when-to-use guidance: 'Call this on EVERY quotation destined for a Quote-with-comment nanopub.' It also clarifies what the tool is not for by separating the human judgement of choosing the claim from the tool's string-search verdict, and it warns against treating high similarity as a pass. This is strong, actionable usage guidance.

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