usaspending-mcp-server

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safe read-only nature is established. The description adds that the type parameter selects the lookup table and that results are filtered codes/names usable in other filters. It does not contradict annotations and provides useful context about the tool's role, though it omits deeper behavioral quirks (e.g., the recipient limit behavior) which are documented in 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 exactly two sentences. The first sentence states the action and object; the second sentence lists the type options and the tool's usage context. There is zero filler, and it is front-loaded with the primary verb and resource.

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 (look up valid codes), the input type options, when to use it (before filtering), and what it returns (codes and names). An output schema is present, so return structure is documented elsewhere. The only minor gap is not mentioning the recipient-specific limit cap, but that is thoroughly documented in the limit parameter schema, so the description is complete for a lookup 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 description coverage is 100%, and each parameter already has a detailed description: type lists all enum values with explanations, search_text is defined as free-text, and limit includes a thorough explanation of its default, range, and special recipient behavior. The description merely repeats the type enum without adding new semantics, so it does not significantly exceed what the schema already provides.

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: 'Look up valid code values for filter fields by searching free-text descriptions.' It enumerates the five distinct lookup tables (naics, psc, cfda, awarding_agency, recipient), making the tool's function concrete. This clearly distinguishes it from sibling tools like search_awards or get_agency, which focus on retrieving award data rather than suggesting filter codes.

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 instructs when to use the tool: 'Call this before filtering awards when you know a description but not the exact code.' It also explains the output's purpose: 'Returns matching codes and names for use in other tool filters.' While it doesn't explicitly name alternative tools or say when not to use it, the contextual guidance is clear and sufficient for a lookup utility.

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?

Annotations already declare read-only, idempotent, and open-world behavior, so the description need not repeat those. It adds meaningful behavioral details: breakdown axes, DEF code filtering, and cross-references to other tools' fields. The HTTP 422 error for missing DEF codes is disclosed in the schema, not the description, but this is acceptable since the schema is part of the tool definition.

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 four sentences, each earning its place: purpose, dimension explanation, DEF code filtering, and cross-reference to other tools. It is front-loaded with the core action and includes no filler, making it easy for an agent to quickly grasp.

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 (5 params, nested objects, output schema), the description covers the essential usage points: what it fetches, dimensions, and DEF code sourcing. It does not mention non-disaster alternatives, but the schema and output schema cover the remaining invocation details, making it sufficiently complete.

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 100%, so the baseline is 3. The description adds value by explaining the dimension parameter's allowed values and the role of DEF codes in filtering, reinforcing the schema's descriptions and helping agents pick correct parameters.

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 fetches disaster/emergency supplemental spending broken down by multiple dimensions, and explicitly mentions COVID-19, hurricanes, and infrastructure law. It distinguishes itself from sibling tools by focusing on DEF codes and disaster-specific spending, avoiding confusion with general spending 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 provides clear context on when to use the tool (for disaster/emergency spending) and explains the importance of the dimension parameter and DEF codes. It does not explicitly name alternative tools or state exclusions, but the context strongly implies usage scenarios, and it references where DEF codes can be found in other 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds value by disclosing that data is for 'the most recent fiscal year', that the sub-agency breakdown is paginated, and that identifiers appear in usaspending_list_agencies results. No contradictions with annotations are present.

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 the core purpose, and follows with identifier guidance. No fluff or repetition—every sentence earns its place, and the structure is easy to scan.

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 an output schema, the description doesn't need to explain returns. It covers the main usage aspects: what data is returned, how identifiers are obtained, and pagination. It could mention error cases or fallback behavior if no identifier is provided, but for a read-only, idempotent tool, this is nearly complete. A 4 is appropriate due to the slight omission of what happens when neither identifier is supplied (0 required params).

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 input schema has 100% coverage with detailed descriptions for all 3 parameters, so the baseline is 3. The description adds extra meaning with concrete examples (097, 012, department-of-defense) and reinforces the mutual exclusivity of toptier_code and agency_slug. This exceeds the schema alone, thus a 4.

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 the tool's function: 'Fetch an agency's fiscal-year overview' with specific elements (mission, budgetary resources, obligations, outlays, sub-agency count, DEF codes), and distinguishes it from siblings like usaspending_list_agencies by focusing on a single agency's details. The verb 'Fetch' and resource 'agency overview' are specific and 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 usage context by explaining the two accepted identifiers (toptier_code and agency_slug) and points to usaspending_list_agencies as the source for these identifiers. It also clarifies the paginated nature of the sub-agency breakdown, implying when to use page parameter. However, it doesn't explicitly contrast with alternative tools for similar lookups, so it stops short of a 5.

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?

Annotations already declare readOnlyHint and idempotentHint, lowering the burden. The description adds meaningful context by listing the specific data fields returned (funding account linkages, subaward count, parent IDV info) and noting the input is a generated ID. It does not detail error behavior or rate limits, but for a read-only fetch, this is sufficient.

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 and well-structured, with each sentence contributing value: purpose, returned fields, input source, and sibling-tool differentiations. No redundant or unnecessary text.

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 an output schema exists, return values need not be described. The description covers the main use case, input source, and the key exclusion (IDV category), while cross-referencing relevant siblings. It is complete for a tool with this complexity.

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 100% and already explains the award_id parameter with an example and source instruction. The description repeats the same guidance without adding new semantic details, so baseline of 3 is appropriate.

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: 'Fetch full details of a federal award by its generated unique award ID.' It clearly distinguishes from siblings by enumerating the returned content (recipient info, agency hierarchy, period of performance, etc.) and explicitly excluding IDV awards, which are handled by a different tool.

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?

Provides explicit usage instructions: use generated_internal_id from usaspending_search_awards as input, and for IDV-category awards use usaspending_get_idv_awards instead. It also mentions pointer to usaspending_get_recipient for recipient hashes, offering clear when-to-use context and 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?

Annotations declare readOnly, idempotent, and closed world, which already establish safety. The description adds behavioral context: the output format (AGENCY-MAIN with example), the linkage intent, and the empty-list behavior for invalid award IDs. No contradiction with annotations.

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 dense sentences that front-load the core purpose, then add chaining guidance, a sibling distinction, and an important edge case. Every sentence adds value without redundant fluff.

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 role as a linking step, the description fully covers how to obtain the required award_id, what the output represents, how to use the output downstream, and how it differs from a similar tool. Combined with rich schema and annotations, nothing essential 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats the award_id source guidance found in the schema and adds an example, but does not significantly enhance meaning beyond what the schema provides. Baseline 3 is appropriate.

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 the specific verb 'List' and identifies the resource as 'Treasury federal accounts that funded an award', with amount and funding agency. It clearly distinguishes from sibling usaspending_get_award account_obligations_by_defc by noting the different breakdown (by account vs. by DEFC).

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?

Provides explicit guidance: the award_id must be a generated_unique_award_id from specific sources (usaspending_search_awards or usaspending_get_award), and the result is meant to chain into usaspending_get_federal_account. It also names an alternative tool and describes the edge case of a non-existent award returning an empty list.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context: it explains the subaward layer, lists the output fields, and mentions the prerequisite check. This goes beyond what annotations provide and does not contradict them.

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 long, front-loaded with the action and resource, and contains no fluff. Every sentence adds information: the purpose, the data revealed, and a usage prerequisite.

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?

With full schema coverage, a known output schema, and annotations indicating read-only/idempotent behavior, the description is sufficient. It covers the purpose, the output summary, and a critical usage precondition, making it complete for an agent to select and invoke the 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 coverage is 100%, so the schema already documents all parameters. The description only indirectly references award_id via 'under a prime federal award' and does not add extra parameter-level meaning. Baseline 3 is appropriate given the strong schema coverage.

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 a specific verb 'List' and resource 'subaward contracts or grants under a prime federal award', clearly distinguishing from sibling tools by explaining that it reveals the sub-contractor/grantee layer. It avoids ambiguity with tools like usaspending_get_award or usaspending_get_award_transactions.

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 instructs to check subaward_count on usaspending_get_award first to confirm subawards exist before calling. This provides a clear precondition and an implied when-not: do not call if subaward_count is zero. It effectively tells the agent when to use this tool versus alternatives.

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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral context: each transaction represents a change event (obligation modifications, performance period extensions, scope changes). This goes beyond the structured annotations to explain the nature of the data. No contradictions with annotations.

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 three focused sentences: what the tool lists, what a transaction means, and when to use it—plus the one key provenance tip. Every sentence earns its place, and 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?

Given the presence of a rich output schema, idempotent/read-only annotations, and only one required parameter, the description fully covers the essential decision points: what the tool does, what the data represents, when to use it, and how to obtain the required award_id. No significant gaps remain.

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%, so the baseline is 3. The description adds extra value by clarifying that the award_id parameter is populated from the generated_internal_id field of usaspending_search_awards, which is not in the schema description. The remaining parameters are adequately described in the schema itself.

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 ('List') and a precise resource ('individual transactions on a federal award'), immediately distinguishing it from siblings like get_award and get_award_subawards. It further clarifies the scope by naming contract modifications and grant amendments as examples.

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 states clearly when to use the tool: to trace spending history and obligation changes over the life of an award. It also provides essential upstream guidance by telling the user that award IDs come from usaspending_search_awards (generated_internal_id). It does not explicitly mention when not to use it, but the context is sufficient.

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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral detail about the response structure, including the per-TAS children breakdown and the connection between federal accounts and appropriations law. No contradictions with annotations.

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 three sentences: first states the purpose with key data items, second provides domain context, third covers sourcing and alternative. It is front-loaded and every sentence earns its place with no redundant text.

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 simplicity (single parameter, read-only, with an output schema), the description sufficiently covers what the tool does, where the parameter comes from, and which sibling tool to use for other breakdowns. No critical gaps remain for correct selection and invocation.

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 input schema already has a 100%-coverage description for account_code, including format, example, and where to find it. The description repeats most of this and adds only a minor example ('DoD Operation and Maintenance'), so it does not significantly expand parameter meaning beyond 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?

The description uses the specific verb 'Fetch' and clearly identifies the resource as 'a federal account's budget data' with enumerated components (obligations, outlays, budgetary resources). It also distinguishes from sibling tools by explicitly mentioning the breakdown tool for alternate needs.

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 provides explicit guidance on when to use this tool versus the alternative: 'For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.' It also tells the agent where account codes come from (search and award federal accounts tools), which is actionable sourcing context.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, covering the safety profile. The description adds useful behavioral context: pagination with an 'honest total count' and the two distinct breakdown axes, which go beyond the annotations. It does not describe edge cases or rate limits, but the annotations and output schema reduce the burden.

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—two sentences—yet dense with information: core action, dimension semantics, account code sources, pagination behavior, and an explicit pointer to an alternative tool. Every clause earns its place, and 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?

Considering the tool's 4 parameters, 1 enum, output schema, and sibling context, the description covers purpose, usage alternatives, parameter semantics, and behavioral notes (pagination). It also tells users where to find account codes, which is critical for correct invocation. There is no obvious gap given the output schema already documents return structure.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds value by elaborating on the dimension parameter ('program activity (what the money funds) vs object class (what it buys — personnel, supplies, contracts)') and clarifying the account_code format (AGENCY-MAIN) and its provenance from specific sibling tools. This enriches the schema descriptions meaningfully.

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 ('Fetch') and a precise resource ('a federal account's obligations broken down by program activity or object class'), immediately clarifying what the tool does. It also distinguishes itself from the sibling tool usaspending_get_federal_account by explicitly stating that the sibling is for metadata and top-level totals.

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 clear usage guidance: use this tool for breakdowns by program activity or object class, and explicitly directs users to usaspending_get_federal_account for metadata/totals. It also tells users where to obtain account codes from three sibling tools, explaining the exact output fields to use, which is practical 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?

Annotations already declare read-only and idempotent behavior. The description adds valuable behavioral context: each row includes generated_unique_award_id for chaining, the award_id must be the parent IDV's generated ID, and the source qualification from get_award. No contradictions with annotations, and the added info helps the agent understand the tool's role.

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?

Three tightly-packed sentences each carry distinct information: what the tool lists, how to chain, and how to obtain the required ID. No redundancy or filler; front-loaded with the action and object.

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 presence of an output schema and strong annotations, the description covers the essential operational context: it defines the input requirement, relates to the parent award tool, and clarifies child type distinctions. No missing behavioral aspects that would prevent correct invocation.

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 covers 100% of parameters, but description enriches award_id with concrete format examples and provenance instructions (generated_internal_id vs generated_unique_award_id). It also clarifies the meaning of the type enum values. This goes beyond the schema's basic 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?

Description clearly identifies the tool as listing child contracts and task/delivery orders under an IDV award, with a specific verb and resource. It distinguishes itself from sibling tools like get_award (parent detail) and search_awards (broad search) by focusing on the child-award relationship. The mention of chaining via generated_unique_award_id clarifies its complementary role.

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?

Provides explicit context: use when the parent award is an IDV, and explains how to obtain the required award ID from usaspending_search_awards or usaspending_get_award. It does not explicitly state when not to use it (e.g., for subawards or transactions), so it falls short of full alternative differentiation, but the guidance is sufficient for agent selection.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description carries a lower burden. It adds valuable context beyond annotations by explaining the UUID level suffixes (-P, -C, -R), the ability to cross-reference UEI/DUNS with external sites (SAM.gov, SEC EDGAR), and the optional scoping behavior for totals. This enriches the agent's understanding of the tool's behavior without contradicting annotations.

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 three sentences, front-loaded with the core purpose, followed by ID format guidance and optional scoping/cross-referencing details. Every sentence earns its place, with no redundant or 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?

With an output schema present, the description need not detail return values. It covers the key workflow: obtaining the recipient ID from specific sources, what the profile includes, and optional parameter usage. For a single-recipient lookup tool with 3 parameters (1 required), this is complete and self-sufficient.

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 100%, so the baseline is 3. The description adds semantic meaning by explaining the recipient_id format (UUID hash with level suffix) and its source, and by clarifying that fiscal_year and award_type are optional parameters that scope the totals. This goes beyond the schema's individual 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 uses a specific verb 'Fetch' and clearly specifies the resource as a 'recipient's full profile' with a concrete list of included fields (address, business type codes, parent organization, alternate names, total transaction and loan amounts). This distinctly differentiates it from sibling tools like usaspending_search_recipients (which finds recipients) and usaspending_get_award (which is award-focused), making the tool's purpose 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 provides clear contextual guidance by stating that recipient IDs originate from usaspending_search_recipients or usaspending_get_award, and that fiscal year and award type can optionally scope the totals. However, it does not explicitly state when not to use this tool or name alternative tools for related scenarios, so it falls short of a 5.

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is clear. The description adds behavioral context by specifying the current fiscal year and the nature of the returned data (top-tier agencies with codes, slugs, amounts). This is useful beyond the annotations, though it does not detail pagination or whether all agencies are always included.

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 concise sentences. The first communicates scope and output fields; the second provides strategic usage guidance and links to the dependent tool. Every sentence earns its place 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?

For a simple listing tool with rich annotations and an output schema, the description fully covers the tool's role in the workflow. It explains what the tool returns, when to use it, and how it connects to other tools, leaving no critical gaps.

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 100% — both 'sort' and 'order' parameters have explicit enums and descriptive text. The description does not add any parameter-level information, but since the schema fully documents them, the baseline of 3 is appropriate.

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 lists 'all top-tier federal agencies' with specific fields (toptier codes, agency slugs, budget authority, obligations). It explicitly positions this as the 'entry point for agency navigation,' distinguishing it from sibling tools like usaspending_get_agency and search 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 says to 'Use this as the entry point for agency navigation' and explains that toptier codes and agency slugs are required for usaspending_get_agency and agency-based filters. This gives explicit when-to-use guidance and points to alternatives, demonstrating strong usage context.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, lowering the burden on the description. The description adds useful behavioral context not fully captured elsewhere: the 90-day publication lag for DoD contracts, the earliest available data date (2007-10-01), and the requirement for ISO 8601 dates. No contradictions with annotations.

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 five sentences long, front-loads the core purpose, then provides the award-type mapping, followed by date and data-lag caveats. Every sentence contributes new, relevant information with no redundancy or filler.

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 complex tool with 14 parameters and nested objects, the description covers the essential context: what it searches, what it returns, how it connects to get_award, award type groupings, date format requirements, and data lag. The detailed schema and output schema handle pagination and parameter-specific semantics. Slightly more could be said about using the filters object vs flat parameters, but that is covered in the schema, so the description is appropriately complete.

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 100%, and the schema itself provides detailed parameter explanations including pagination caps, recipient_id ignoring behavior, and per-field descriptions. The description adds a high-level summation of filter categories and an award-type legend, but the legend is already present in the schema's award_type_codes property. Therefore, it does not meaningfully add beyond the schema, so the baseline 3 is correct.

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 ('Search federal awards') and enumerates the supported search dimensions (keyword, recipient, agency, award type, NAICS code, location, date range). It distinguishes itself from sibling search tools by focusing on federal awards and explicitly mentions producing award IDs for use with usaspending_get_award, making its role clear.

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 for how the tool fits into a workflow: search for awards, then use the generated IDs with usaspending_get_award. It does not explicitly state when-not-to-use or name alternatives, but the reference to a sibling tool and the focused scope give sufficient usage guidance. Lacks explicit exclusions, so a 4 is appropriate.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. Description adds behavioral context by specifying returned fields (account numbers, names, managing agencies, budgetary resources) and cross-tool relationships, though it doesn't mention pagination specifics which are in 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?

Three sentences, all information-dense: first defines the operation and return values, second links to the detail tool, third explains agency code lookup. No filler.

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?

With a full input schema, output schema presence, and annotations covering safety, the description is sufficient for the tool. It explains the core use, return fields, and related usage, making it complete for a search/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?

Schema description coverage is 100%, with each parameter documented. The description reinforces the agency_identifier guidance (3-digit codes, list_agencies) already present in the schema, adding no novel parameter semantics beyond what the schema provides, so baseline 3.

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 states 'List and keyword-search federal accounts by agency identifier or title keyword' with a specific verb and resource, distinguishing it from sibling tools like usaspending_get_federal_account by indicating it returns a list of accounts with identifiers.

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 guides users to use usaspending_get_federal_account for full budget detail using account_number from results, and usaspending_list_agencies for agency_identifier codes, providing clear alternatives and workflow.

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?

Beyond the readOnly/idempotent annotations, it explains pagination behavior, page_metadata.total, and recipient level semantics (P/C/R). It also clarifies that results include hash IDs that can be chained into another tool, adding meaningful operational context not inferred from annotations alone.

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 four sentences, each serving a distinct purpose: defining the search scope, listing return fields, explaining pagination, and connecting to the recipient profile tool. It is front-loaded with the primary use case and has 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?

With an output schema present and rich annotations, the description fully covers tool behavior: search criteria, return fields, pagination mechanics, result chaining, and hierarchy level definitions. It gives an agent everything needed to decide when to call this tool and how to interpret the first page of results.

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 already provides 100% coverage of all parameters including descriptions for keyword, page, limit, and award_type. The description adds limited additional parameter nuance—mostly clarifying keyword accepts identifiers and partial matches, which is already in the schema. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 for organizations or individuals receiving federal funds by name, UEI, or DUNS. It distinguishes itself from sibling tools like usaspending_get_recipient by specifying the search and pagination aspects, and mentions the returned fields (hash IDs, total award amounts, hierarchy).

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 provides clear context for when to use the tool (searching by identifier/name, paginating results) and explicitly points to usaspending_get_recipient as the follow-up for full profiles. However, it does not explicitly state when not to use this tool vs alternatives, such as usaspending_search_awards for award-focused searches.

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?

Annotations already declare readOnly, openWorld, and idempotent, so the safety profile is covered. The description adds the behavioral detail that it returns only top items with obligation amounts and lists the supported breakdown dimensions. No contradictions or misleading statements exist.

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?

Three sentences: the first states the core function and dimensions, the second clarifies the output nature, and the third gives cross-tool chaining advice. No filler, no redundancy, and key 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 full parameter documentation, an output schema, and annotations covering safety. The description adds the necessary selection context and downstream chaining guidance, making it complete for an agent to decide when and how to invoke the 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 description coverage is 100%, with every parameter (category, filters, page, limit) already documented and a rich enum for category. The description does not need to add parameter-level detail, and it stays at the baseline by not duplicating schema information or providing extra meaning beyond the categories already enumerated in 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?

The description opens with the specific verb 'Aggregate' and names the resource ('federal spending') plus the grouping dimensions (NAICS, PSC, agency, CFDA, recipient). It also notes a concrete output ('top items with obligation amounts'), clearly distinguishing it from geographic or time-based siblings.

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 states a use case ('trend and breakdown analysis') and gives chaining guidance to search_awards and autocomplete_filters. However, it does not explicitly name alternative tools spending_by_geography or spending_over_time as the better choices for location or time-series analysis, so exclusions are left implicit.

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?

Annotations already flag readOnly, openWorld, and idempotent hints, but the description adds valuable behavioral context: the upstream endpoint is not paginated (returns all matches in one response), the limit parameter caps client-side, and nationwide county queries exceed 3,000 areas. It also discloses the FIPS/abbreviation constraint, which is not apparent from annotations.

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 covers use cases, and the third gives an essential usage constraint. Every sentence adds unique value with no redundancy or fluff.

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?

With an output schema present and 100% parameter schema coverage, the description doesn't need to explain return values. It covers the main usage context (what the tool aggregates, granularity options), the critical input format caveat (FIPS vs place names), and a guidance about per-capita analysis with Census data. This is sufficient for an AI agent to select and invoke the tool 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 coverage is 100%, so the baseline is 3, but the description adds critical semantics beyond the schema: geographic filters accept FIPS codes and 2-letter state abbreviations, not place names. It also explains the limit parameter's behavior in the context of an unpaginated upstream, which is not in 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 opens with a specific verb and resource: 'Aggregate federal spending by state, county, or congressional district.' This clearly distinguishes it from sibling tools like spending_by_category (categories) and spending_over_time (time series), and the use cases (per-capita analysis, regional comparisons, mapping) reinforce the purpose.

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 states when to use it ('Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns') and provides a key prerequisite ('Resolve place names to FIPS codes... before applying location filters'). However, it does not explicitly mention when *not* to use it or name alternative sibling tools, so it falls slightly short of a 5.

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?

Adds useful behavioral context about the US government fiscal year convention (Oct–Sep, month 1 = October) and indicates return content (per-period totals). However, the claim of 'optional breakdowns by award category' is not supported by any exposed parameter in the input schema, making part of the behavioral disclosure unsubstantiated.

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?

Three sentences with the main action front-loaded; the fiscal-year clarification is valuable. The final sentence is compact but contains the unsupported 'optional breakdowns' claim, so it is not fully clean.

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 read-only time-series tool with robust annotations, a 100% documented schema, and an output schema, the description covers the core grouping semantics and intended use. It could be fuller by explicitly contrasting with spending_by_category or spending_by_geography, but the essential context is present.

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 100%, so baseline is 3. The description repeats the fiscal-month convention and maps high-level filter categories to the filters object, but adds no parameter syntax or format details beyond what the schema already provides.

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 uses specific verb 'Fetch' with resource 'aggregated federal obligation amounts grouped by fiscal year/quarter/month'. This clearly distinguishes the tool from sibling category/geography spending tools by emphasizing time-series grouping.

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 frames usage 'to trace spending trends in a specific area' and lists filter dimensions (award type, agency, recipient, keyword, NAICS). It does not explicitly name alternatives or when-not conditions, but the intended context is clear from the description and sibling names.

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