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

With no annotations, the description carries the full burden of behavioral disclosure, and it succeeds: it explains what is returned, what is dropped, how the drop is reported under `neighbourhood`, why `citedPaper` should be trusted over `paperDoi`, and why missing steps in `stepsPresent` are normal. This is unusually transparent.

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 purpose and use cases, then moves into output behavior and caveats. Every sentence adds distinct value, including the concrete 64-of-98 example, which illustrates the need for the compact projection 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 and no annotations, the description covers what an agent needs to know: what the tool returns, what it deliberately omits, and how to interpret tricky fields like `citedPaper`, `disagreesWithReported`, and `stepsPresent`. It is complete for practical invocation and interpretation.

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 description gives semantic meaning to `uri` ('published nanopub URI') and indirectly hints at `depth` via the 'depth-5 neighbourhood' discussion, but it never explains `max_nodes`. Since schema description coverage is 0%, the description partially compensates but leaves one parameter underdocumented.

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 names the specific resource ('FORRT chain(s) reachable from a published nanopub URI') and the precise action ('Call this to see an existing chain'), while contrasting it with the raw Science Live constellation. This clearly differentiates the tool from its raw sibling and leaves no ambiguity about what it returns.

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 concrete trigger scenarios: before starting a replication, when extending someone else's chain, or after publishing your own. It does not explicitly name an alternative tool or say 'do not use when...', but the context is clear enough for an agent to decide when to invoke it.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses that the response is raw/unprojected, very large (~330 KB for a single chain), and contains data mostly belonging to other studies. This gives the agent important expectations about size and content. It does not explicitly state that the operation is read-only, but the 'response/debugging/investigating' framing strongly implies a non-mutating fetch.

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 compact and front-loaded. The first sentence states exactly what the tool returns, the second gives the use case, and the third provides the alternative plus a size warning and a tuning hint. Every sentence earns its place and there is no redundant wording.

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?

The description covers the tool's purpose, use case, size, and one parameter behavior, but it omits the meaning of `uri` and `max_nodes`, which are essential for calling the tool correctly. There is no output schema, so the description should provide more return-shape detail; it does describe 'every node and edge,' but the parameter gaps prevent full contextual completeness.

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%, so the description must compensate by explaining the parameters. It only explains `depth` ('Lower `depth` to shrink the walk') and gives no guidance on `uri` or `max_nodes`. The agent is left to guess what `uri` should reference and what `max_nodes` controls. This is a significant gap for a tool with three parameters and no schema-level descriptions.

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 what the tool returns: 'The unprojected /np/constellation response, including every node and edge.' It uses a specific resource and distinguishes itself from the sibling `constellation` tool by calling this the raw/debugging variant. An agent can immediately tell what this tool does and how it differs from the normal `constellation` endpoint.

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 states when to use this tool: 'For debugging the graph itself or investigating an upstream data problem.' It also names the preferred alternative: 'Prefer `constellation` for normal use.' It even provides a practical tuning hint—'Lower `depth` to shrink the walk'—which gives actionable guidance for invocation.

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

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

With no annotations, the description carries the behavioral disclosure burden. It adds valuable context: 'Cheap, offline, and no network' tells the agent this is a low-cost, safe first call. It does not explicitly say 'read-only', but the listing/lookup wording and zero mutation implications make that reasonably clear.

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 very short, front-loads the core purpose, and uses a second sentence for actionable guidance. No filler or redundant restatement of the tool name.

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 zero-parameter catalog tool, this is nearly complete: it states what is listed, when to call it, and why it is safe/cheap. It does not explicitly describe the output format, but the name and phrasing make the return value self-evident.

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 tool has zero parameters, so the baseline is 4. The description goes further by explaining how its output informs what to pass to template_fields and vocabulary, which helps the agent understand the tool's role in the broader workflow.

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 the resource clearly: chain steps and vocabularies the server can look up. It lacks an explicit imperative verb like 'lists' or 'returns', but the meaning is unambiguous and distinct from the lookup-focused sibling tools.

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 explicitly says 'Call it first if you are unsure what to pass to template_fields or vocabulary', naming the exact sibling tools and the condition that triggers this tool. 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.

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

With no annotations, the description carries the full burden. It discloses the return granularity ('one entry per completed chain'), the key fields including the specially important 'limitations', and a behavioral caution: published chain steps are signed records with URIs and should not be re-derived. It does not mention errors or edge cases, but the read-only nature is clear from 'returns'.

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 structured as an opening definition, a detailed output explanation, and a usage paragraph. It is slightly more verbose than strictly necessary, but the additional sentences earn their place by explaining output semantics and use cases. The most important information is front-loaded.

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?

The tool has one parameter and no output schema, so the description must explain both input meaning and return content. It covers input URI semantics, output fields, usage intentions, and a caution about citation. It omits output format and error behavior, but for a simple retrieval tool this is a minor gap.

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%, so the description must compensate for the single 'uri' parameter. It does so by specifying that the URI must be a published nanopub URI in a constellation, which gives meaningful domain context beyond the bare parameter name. Exact URI format is not provided, but enough guidance exists for correct invocation.

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 opens with a clear statement of what the tool provides: prior claims about a paper, as the starting point for replication or fresh study. It specifies the resource ('published nanopub URI in a constellation') and the output shape ('one entry per completed chain'), making it distinct from sibling validation and lookup tools.

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 tells an agent when to use this tool: to avoid duplicating existing replications, to choose a CiTO relation, and to find still-open parts of a claim. It does not name alternative siblings or state when not to use it, but the usage contexts are concrete and actionable.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool asks the registry, what `resolves: false` means, that well-formed DOIs can be fabricated, and what fields are returned on success. This gives the agent a realistic model of the tool's behavior.

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 question and usage instruction, followed by behavior and return details. Each sentence adds information, though the point about fabricated DOIs is slightly expansive; still, it reinforces an important trust boundary.

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 single-parameter tool with no output schema and no annotations, the description covers purpose, when to call it, false/true semantics, return fields, and accepted input formats. Nothing essential for correct invocation is missing.

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 only defines `doi` as a string with 0% description coverage, so the description must compensate. It does by specifying accepted forms: bare (`10.…`), URL, or `doi:`-prefixed. This is meaningful format guidance beyond the schema, though an example would have made it even clearer.

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 question 'Does this DOI resolve, and to what?' clearly states the tool's purpose with a specific verb and resource. The description further specifies it is for DOIs destined for nanopub fields, CITATION.cff, or CiTO citations, distinguishing it from the non-DOI sibling tools.

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 says 'Call it on every DOI destined for a nanopub field, CITATION.cff, or a CiTO citation,' giving a clear trigger condition. It also instructs not to publish when `resolves: false`, providing actionable guidance beyond mere invocation.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses concrete behavior: returning field ids, prompts, required/repeatable flags, constraints like regex/prefix/datatype, and allowed values; plus source semantics for 'live' vs 'bundled-snapshot' and 'driftedFromSnapshot.' It also clarifies that templates may be stale when the network is unavailable.

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 every sentence earns its place: purpose, timing, return contents, step values, and source-freshness semantics are all relevant. The most important scoping information is front-loaded before implementation details.

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 two-parameter lookup tool with no output schema and no annotations, the description is remarkably complete. It tells an agent what the tool returns, which parameter values are valid, what the freshness/drift states mean, and when to call it. The only small gap is explicit treatment of the `live` parameter, but it is not enough to undermine completeness.

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%, so the description must compensate. It does this very well for `step` by documenting accepted aliases and listing all known step values, but it does not directly explain the `live` boolean parameter beyond the broader 'live' vs 'bundled-snapshot' distinction in the source discussion.

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 opens with a precise definition: 'The exact form fields of one FORRT chain step, from the live template.' It names the resource, scope, and what the tool returns, and the contrast with validation/verification siblings ('Call this BEFORE drafting any nanopub field') makes its role unambiguous.

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 timing context: 'Call this BEFORE drafting any nanopub field,' and explains why the template itself is the schema. It also enumerates known step aliases and values. However, it does not explicitly name alternative tools or state when not to use this tool.

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

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

With no annotations, the description carries the full burden of explaining behavior. It thoroughly discloses what the validator catches, including superseded template URIs, dropped prefill keys, shape violations, regex violations, unresolved tokens, and invalid DOIs. It does not explicitly state whether the operation is read-only or makes network calls, but the 'Check' framing and detailed error semantics provide strong behavioral transparency.

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 a clear purpose sentence and then uses bullets for detailed validation rules. It is longer than average, but the length is justified by the complexity of the validation checks. Slight tightening around repeated 'what it catches' phrasing would improve it, but it remains well structured.

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?

The description provides rich contextual guidance: when to run, what the validator checks, what it does not check, and which fields are exempt. It does not fully describe the return shape beyond the `readyForWizard` flag and 'nothing came back as an error', and it omits parameter semantics. Given the tool's complexity and lack of output schema, this is a minor but real gap.

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 the description does not explain the `path` or `live` parameters. It references the default file `nanopubs/chain-draft.json`, which implies what `path` might point to, but `live` is completely undocumented. The description does not compensate for the schema's lack of parameter descriptions.

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: 'Check `nanopubs/chain-draft.json`'. It also explicitly distinguishes this tool from the sibling validate_draft: 'validate_draft checks the authoring input; this checks the artifact.' This makes the tool's role unambiguous.

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 precise timing: run at the end of Phase 5b, after `pixi run build-chain-draft`, and before pushing the file or opening the wizard URL. It also clarifies when results indicate readiness and explicitly contrasts it with validate_draft, giving an agent clear selection criteria.

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

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

With no annotations, the description carries full responsibility, and it is exceptionally transparent: it enumerates checks (template, enum, regex, DOI registry, Wikidata), defines the three severities, explains placeholder conventions, notes step inference from filenames, and describes the unfilled-skeleton behavior. This goes well beyond a generic 'validates' statement.

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 long but every sentence earns its place, and it is well-structured: purpose first, then usage, then severity semantics, then edge cases. The severity block and placeholder convention explanation are dense but scannable.

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 or annotations, the description covers purpose, usage, validation behavior, severity semantics, placeholder conventions, and step handling. The main gap is the unexplained `live` parameter, and the return value shape is only implied via `publishable` and severities.

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%, so the description must explain all parameters. It richly explains `step` (inferred from filename, override for unusual names) but says nothing about `path` or, more importantly, `live`, whose boolean semantics and default true are not inferable from the schema.

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?

States a specific verb and resource: 'Check one drafted nanopub against its template and the real world.' The singular 'one drafted nanopub' and the focus on template/real-world validation distinguish it from siblings like validate_drafts and validate_chain_draft without needing to open schemas.

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?

Explicitly instructs 'Run this on every draft before publishing' and positions it as the pre-flight checklist, which is strong when-to-use guidance. It does not name alternative tools or state when not to use them, so it stops short of full exclusionary guidance.

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

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

With no annotations, the description carries the full burden. It discloses output semantics ('publishable true only when no draft has an error') and a notable limitation about prose/markdown values being reported as coverage warnings rather than missing. This is substantive behavioral context.

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 compact and front-loaded. The first sentence states the core function, the second adds timing and result semantics, and the third adds an important caveat. Every sentence 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?

The description covers usage timing, output summary, and a known limitation, which is helpful. However, there is no output schema, no annotations, and the 'live' parameter is left undefined, so an agent still has a meaningful gap in understanding the full contract.

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%, so the description must compensate. It indirectly explains that directory points to a drafts directory, but it never explains the 'live' parameter, leaving one of only two parameters semantically 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 description states a specific verb and resource: 'Check every draft in a nanopubs/drafts/ directory at once.' This clearly identifies a batch validation operation and distinguishes it from the singular sibling validate_draft.

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 explicit timing guidance: run before Phase 5b and again before announcing. It does not explicitly discuss when to prefer validate_draft or verify_chain, but the intended context is clear.

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

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

With no annotations, the description carries the full burden and delivers: 'Read-only: it never edits, retracts or supersedes — a failing row is for a human to act on.' It also explains the green flag, the CiTO agreement check, and which 'not enumerated' results are warnings vs fine, going well beyond minimal.

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?

Every sentence earns its place, from the front-loaded purpose to the mode caveat at the end. The bulleted check list and bolded key terms make the long content scannable without wasting words.

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 high-complexity tool with no annotations and no output schema, the description is nearly complete: it covers what is checked, what counts as a failure, and mode semantics. It falls just short by not describing the report/return format beyond the green flag and not addressing repo_url.

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%, so the description must compensate. It richly explains published_path (ledger vs directory) and mode (all values, defaults, and effect on required checks), but never mentions the repo_url parameter at all — leaving one of three parameters undocumented.

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?

Opens with 'Verify a published FORRT chain. Run this before announcing it anywhere,' a specific verb and resource that also separates it from draft-oriented siblings like validate_chain_draft. The detailed checks further nail down exactly what 'verify' means in this context.

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?

Gives clear when-to-use: before announcing a chain, pointing at PUBLISHED.md. It explains mode behavior but never explicitly says when not to use it (e.g., drafts should go to validate_chain_draft), so it stops at clear context without exclusions.

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

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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses provenance (template or value-list nanopub), guarantees that returned values are exactly what the form will accept and nothing else, and explains semantic traps like validation_status being an evidence-based verdict and study_type's Reproduction vs Replication distinction. It does not explicitly state side-effect-free behavior or error handling, but the read-only lookup nature is strongly implied by 'allowed values.'

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, followed by a clear usage line, a compact names list, and three bulleted caveats. Every sentence adds decision-relevant information, and the length is justified by the semantic pitfalls an agent must know to avoid invalid drafts. No filler or repetition.

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 no annotations, the description is nearly complete: it states what is returned, which names are valid, when to use it, and which sibling to call instead in ambiguous cases. The main omissions are the `live` parameter's meaning and any explicit description of the response shape, which would make it fully self-contained.

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%, so the description must compensate. It does so for the required `name` parameter by enumerating all six valid names and explaining the semantics of three of the trickiest ones. However, the `live` parameter is never mentioned, so one of the two parameters remains undocumented outside the bare schema. This is a real but minor gap.

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 opens by identifying the exact resource: the allowed values of a FORRT controlled vocabulary from its template. It then names the six concrete vocabularies it serves (claim_type, study_type, validation_status, confidence_level, cito_relation, pico_question_type), so an agent can distinguish this from sibling tools like template_fields or validate_draft. This is a specific verb-plus-resource statement, not a tautology.

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 explicitly says 'Use it whenever a draft needs...' and then gives strong when-not-to-use guidance: pico_question_type is PICO-only, PCC questions have no type field, and Quote-with-comment has neither type nor label. It also directs the agent to call template_fields on the actual anchor (01_quote, 01_pico, 01_pcc) rather than assuming all anchors match. This is exemplary routing between related tools.

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

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

With no annotations provided, the description carries the full behavioral burden. It transparently discloses that the tool returns candidates with descriptions and P31/P279 types, marks typeMatches, annotates rather than filters, and deliberately does not choose a single result. This gives the agent a clear mental model of the tool's behavior.

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 organized into three tight paragraphs, each earning its place: purpose, expected_type behavior with an example, and zero-candidate handling. No filler or redundant phrases; it is informative without being bloated.

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 and no annotations, the description covers return values, type-checking behavior, and failure handling well. The only notable omission is `limit`, but the tool's core contract is clear enough for an agent to use it correctly.

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%, so the description must compensate. It explains `query` indirectly as 'a term' and `expected_type` well with concrete QID examples and its effect on candidate matching. However, `limit` is never mentioned, leaving one of three parameters semantically undocumented.

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 opens with a specific verb and resource: 'Find real Wikidata items for a term, and type-check them.' It clearly distinguishes the tool's role from siblings by scoping it to 'every Wikidata topic or keyword destined for a nanopub field' and by explicitly noting it does not choose among ambiguous candidates.

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 explicit when-to-use guidance ('Call it for every Wikidata topic or keyword destined for a nanopub field') and when-not behavior ('A zero-candidate result means leave the field empty or try another label'). It also warns against a common misuse: 'Never fall back to a QID from memory.'

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