Primary-document shelf metadata for a state or program ref (title, kind, publication date, source URL, sealed hash where held). tier 'golden' = fidelity-verified; tier 'abstract' = integrity-verified but preliminary, attribute as such.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | a ref from search_programs, e.g. 'rhtp/states/oklahoma' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It explains tier meanings and that 'sealed hash' is conditional ('where held'), but does not disclose authentication needs, error behavior for invalid refs, or whether the actual document is returned (implied metadata only).
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?
Two sentences, both front-loaded with key purpose and tier details. No unnecessary words or redundancy.
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 simple tool with one parameter and no output schema, the description covers output fields and tier semantics adequately. Minor gap: does not explicitly state it returns metadata only, not the document itself, but this is implied.
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 100% for the single 'ref' parameter. The description adds value by specifying that the ref originates from search_programs and provides an example ('rhtp/states/oklahoma'), which aids understanding beyond the schema description.
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 states it retrieves document shelf metadata for a state/program ref, listing specific fields (title, kind, publication date, source URL, sealed hash) and explaining tier distinctions ('golden' vs 'abstract'). This verb-resource specification distinguishes it from siblings like get_state_profile or search_programs.
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 implies usage when you need document metadata for a ref from search_programs, but lacks explicit when-to-use or when-not-to-use guidance. No direct comparison to siblings, though context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct aspect: document metadata, state profiles, sub-initiative ledgers, deadlines, program search, and cryptographic verification. No overlapping purposes.
All tools use a consistent verb_noun pattern (get_, list_, search_, verify_) in snake_case, with no deviations.
6 tools is well-scoped for a focused data-access server, covering key query operations without being excessive.
The tool set covers core data retrieval needs: documents, profiles, ledgers, deadlines, search, and verification. The references to follow-up tools indicate thoughtful integration.
