data-access

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.

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

With no annotations, description carries full burden. It explains output components and tier meanings, but does not mention side effects, authentication, rate limits, or data freshness. For a read operation, coverage is adequate but not detailed.

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 efficiently deliver all key information: resource identity, output components, and variant explanation. No wasted 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?

Given no output schema, description outlines return fields and tier interpretations. Missing details like output structure (e.g., JSON object) or error conditions, but acceptable for a focused profile tool.

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 has 50% coverage (state described). Description adds meaning to response_format param via example. Also explains tier concepts, adding context beyond 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?

Description clearly identifies the resource as a state's RHTP profile with components like award, lead agency, initiative summaries. It distinguishes from siblings (e.g., get_document) by specifying a state-level aggregate, but lacks an explicit verb like 'retrieve' or 'get'.

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?

No guidance on when to use this tool versus alternatives (e.g., search_programs, get_subinitiative_ledger). Does not specify prerequisites or 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 burden. It describes the output content (tiers and data fields) but does not disclose behavioral traits such as read-only nature, authentication requirements, rate limits, or error handling. The explanation of tiers adds value beyond the schema.

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 concise at two sentences, front-loading the primary purpose and then adding tier details. Every sentence adds value with no 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?

Given the tool has 3 parameters, no output schema, and sibling tools, the description covers the output's two-tier distinction but omits details on pagination (cursor), filtering (tag), and the complete return structure. It is minimally complete for a generic ledger retrieval but lacks depth for complex use cases.

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 33% (only 'state' is described implicitly). The description does not add meaning to parameters like 'tag' or 'cursor' beyond what the schema provides. For a low-coverage scenario, the description fails to compensate, leaving key 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 description clearly states it retrieves a funded sub-initiative ledger for a state, detailing the content (who, what, dollars, RFA timing) and explaining tier labels. It distinguishes from siblings by specifying the sub-initiative focus, though it does not explicitly differentiate from related tools 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?

No guidance is provided on when to use this tool versus alternatives. The description implies usage when needing funded sub-initiative ledger data for a state, but it lacks explicit context, exclusions, or mentions of sibling 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, the description bears full responsibility for disclosing behavioral traits. It explains the meaning of tier values but does not address whether the operation is read-only, pagination, ordering, rate limits, or what 'across your entitled states and programs' entails behaviorally.

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 concise with two sentences: one stating the purpose and one explaining tier semantics. No extraneous information is present, and the structure is efficient.

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 no output schema and sparse parameter descriptions. The description provides tier context but omits crucial details about return format, data structure of deadlines, how the 'states' parameter filters, and overall behavior. It is incomplete for a list tool.

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 adds no meaning to the parameters 'before' and 'states' beyond what the input schema already provides. Schema description coverage is 50% (only 'before' documented), and the description does not compensate by explaining their use or format, leaving the agent with incomplete parameter understanding.

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 uses specific verbs ('list') and resources ('deadlines', 'solicitations') and distinguishes itself from siblings like 'get_document' or 'get_state_profile' by focusing on deadlines across states and programs. The tier clarification ('golden', 'abstract') adds specificity.

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 for retrieving open/closing solicitations and key dates but does not provide explicit guidance on when to use this tool versus alternatives or mention any prerequisites or conditions. No when-not instructions are given.

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 burden. It discloses search behavior, result format, and the fidelity distinction between tiers. Missing details include explanation of the 'cursor' parameter and potential rate limits, but the core behavioral traits are 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 two sentences, front-loaded with purpose, followed by result and tier details. Every sentence adds value; no extraneous content.

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 the tool's complexity (multiple entity types, result tiers, cursor for pagination) and no output schema, the description only partially covers what the agent needs. It lacks explanation of the 'kind' filter, cursor usage, and the structure of a 'stub' or 'refs'. Basic use is enabled, but deeper understanding requires inference.

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 covers 3 parameters but only 'query' has a description; schema coverage is 33%. The description adds value for the query parameter ('keywords') and overall context, but does not explain 'kind' (despite enum) or 'cursor'. Low schema coverage demands more compensation than provided.

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 the tool searches the verified federal-funding corpus by keywords, specifying the entity types (states, initiatives, sub-initiatives, programs). The verb 'search' and resource are specific, and it distinguishes this from sibling tools which are retrieval-focused (e.g., get_document).

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 explains the result format (ranked stubs with refs) and defines the two tiers (golden vs abstract) with usage guidance ('attribute as such'). However, it does not explicitly mention when not to use this tool or list alternatives, leaving the agent to infer from sibling names.

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?

The description reveals the verification steps (recomputing hash, checking signed manifest, Ed25519 signature) and states no cost. Annotations are absent, so the description carries the burden and does so adequately.

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 efficiently cover functionality, optional parameter usage, and cost. No wasted 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?

The description lacks output specification; agents cannot infer whether the result is a boolean, JSON, or error. For a verification tool, this is a gap in 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 coverage is 100% with descriptions for both parameters. The description adds no new parameter info beyond the schema, so baseline 3 applies.

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 the tool verifies an artifact by recomputing SHA3-256, checking manifest and signature. It distinguishes from sibling tools like get_document which retrieve data, not verify.

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 provides clear context: pass sha3_256 to attest a copy, and notes verification is free. It does not explicitly define when not to use it or compare to alternatives, but the context is clear.

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