vocabulary

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.