usaspending-mcp-server

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

Annotations already declare readOnly, openWorld, idempotent. Description adds that it returns matching codes and names, providing useful behavioral context without contradiction.

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 well-structured sentences: purpose, parameter explanation, usage guidance. No wasted words, front-loaded with core functionality.

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 3 parameters, presence of output schema, and annotations, the description fully covers behavior, parameters, and return value. No 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 coverage is 100%, so baseline is 3. Description adds meaning by explaining the purpose of the type parameter with enum values and clarifying search_text usage, surpassing baseline.

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 states verb ('look up'), resource ('valid code values for filter fields'), and context ('by searching free-text descriptions'). It distinguishes from sibling tools which are primarily for spending or award data retrieval.

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 advises calling this tool before filtering awards when you have a description but not the exact code. Does not specify when not to use, but overall guidance 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?

Annotations include readOnlyHint, openWorldHint, idempotentHint, and the description complements these by noting that def_codes are required for non-overview dimensions. No contradictions, and the description adds behavioral context beyond 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 long, well-structured, and front-loaded with the core functionality. Every sentence adds necessary context without superfluous detail.

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 parameters, 1 required, 100% schema coverage, and an output schema), the description is complete. It explains the dimension parameter, the def_codes filter requirement, and cross-references other tools for DEF codes.

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%, but the description adds value by explaining that def_codes is required for agency, cfda, recipient, and geography dimensions, and by describing each dimension's purpose. This goes beyond what the schema 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 clearly specifies the tool fetches disaster and emergency supplemental spending broken down by agency, CFDA, recipient, or geography. It lists all dimensions and mentions DEF code filtering, making the purpose precise and distinct from 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?

The description explains when to use this tool (for disaster/emergency spending) and provides context about DEF codes from other tools. While it doesn't explicitly state when not to use it, it gives enough guidance for selecting it over 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 provide readOnlyHint and idempotentHint, and the description adds value by detailing the returned data (mission, budget, DEF codes, sub-agency breakdown), thus fully informing the agent 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 concise, with two sentences. The first lists key return fields, the second explains input options and cross-reference. No unnecessary 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 the presence of an output schema, the description doesn't need to detail return format. It fully covers input requirements and behavioral context, making it complete for the tool's 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?

The input schema already describes the two parameters and their mutual exclusivity. The description adds context about where these IDs come from (usaspending_list_agencies and award search results), providing additional semantic value.

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 fetches an agency's current fiscal year overview with specific data fields (mission, budget authority, obligation totals, sub-agency count, DEF codes) and differentiates from siblings like usaspending_list_agencies by focusing on a single agency's details.

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 that the tool accepts either a toptier_code or agency_slug from usaspending_list_agencies or award search results, implying when to use it. However, it lacks explicit guidance on when not to use it or 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=true and idempotentHint=true, so the agent knows this is a safe, idempotent read operation. The description adds behavioral context by specifying the exact response fields (contract/assistance data, recipient info, etc.) and noting that input comes from a search tool. This is above the baseline but not exhaustive.

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 a single, well-structured paragraph. It front-loads the primary purpose, then lists what is returned, and concludes with cross-references to sibling tools. Every sentence is informative and there is 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?

Given that the tool has only one parameter and an output schema exists (though not shown), the description is exceptionally complete. It covers input format, usage context, alternatives, and related sibling tools. No additional information is needed for correct agent usage.

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 single parameter 'award_id' has 100% schema coverage and the description explains its purpose with a concrete example and the source (generated_internal_id from usaspending_search_awards). This adds significant meaning beyond the schema's 'minLength' constraint.

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 full details of a federal award by its unique ID, and lists the types of data returned (contract/assistance, recipient info, agency hierarchy, etc.). It distinguishes from the sibling tool usaspending_get_idv_awards by noting that IDV-category awards require that tool instead.

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 use generated_internal_id from usaspending_search_awards as input. It also provides clear guidance on when not to use this tool: for IDV-category awards, use usaspending_get_idv_awards instead. Additionally, it suggests related tools for recipient hashes (usaspending_get_recipient) and NAICS codes (usaspending_search_awards filters).

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 as true, indicating safe read operation. The description adds value by explaining the tool reveals the sub-contractor/sub-grantee layer and listing output fields. 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?

Two sentences: first states purpose and output, second provides a usage hint. Extremely concise, front-loaded with key information, 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 the rich input schema, annotations, and existence of output schema, the description covers the tool's purpose, usage hint, and output fields adequately. It could mention pagination, but that is implicit from parameters. Overall, it is complete enough for an agent.

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 briefly mentions output fields (e.g., subaward number, amount) but does not add semantic meaning to the parameters 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?

The description explicitly states 'List subaward contracts or grants under a prime federal award' with a clear verb and resource, and it distinguishes from sibling tools by focusing on subawards. It also outlines the fields shown in each row, enhancing clarity.

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 a specific precondition: 'Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.' This guides the agent on when to invoke the tool. It lacks explicit when-not-to-use or alternatives but is still helpful.

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 mark it as read-only and idempotent. The description adds behavioral context by explaining that each transaction is a 'change event' and enumerating examples (obligation modifications, period extensions, scope changes), which is valuable beyond the structured fields.

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: purpose, what transactions represent, usage guidance. It is concise and front-loaded with the core function. However, it could be slightly more structured or use bullet points for quick scanning.

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 listing tool with output schema (not shown), the description sufficiently explains purpose, input source, and what the transactions represent. It does not need to detail return values. It is complete enough to guide 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 coverage is 100% with descriptions for each parameter. The description adds minor value by noting the award_id comes from a specific field (generated_internal_id), but overall does not substantially enhance parameter understanding 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 clearly states it lists individual transactions on a federal award, each representing a change event. It distinguishes from siblings by tying award IDs to a specific sibling tool (usaspending_search_awards).

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 this to trace the spending history and obligation changes over the life of an award,' providing clear context for when to use. It also explains where award IDs come from, guiding the agent to first call usaspending_search_awards. No explicit when-not, but annotations imply safe read operation.

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 read-only and idempotent behavior. The description adds that the tool returns account metadata and current fiscal year financial totals, which is consistent and adds value. No contradictions.

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 plus a descriptive sentence, no wasted words. Front-loaded with purpose and return data. 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?

Tool is moderate complexity with one parameter. Description explains what is returned (obligations, outlays, resources, metadata, totals) and the relationship to awards. Output schema exists, so no need to detail 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?

Schema covers 100% of the single parameter. Description adds meaning: format example, origin from usaspending_get_award, and field reference, going beyond 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?

Description clearly states 'Fetch a federal account's budget data' with specific fields (obligations, outlays, resources). It distinguishes from sibling tools by mentioning that account codes come from usaspending_get_award, avoiding 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?

Explains that federal accounts connect appropriations law to spending and that account codes are formatted as AGENCY-MAIN, providing context on when to use this tool. Does not explicitly state when not to use it, but gives clear guidance via examples.

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 readOnlyHint=true and idempotentHint=true, so the description does not need to cover safety. It adds useful behavioral context like each row includes generated_unique_award_id for chaining, which enhances 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 three sentences, front-loaded with the main purpose, no redundant information. Every sentence is essential.

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 and the existence of an output schema, the description fully covers usage, parameter requirements, and return value chaining. No 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?

With 100% schema coverage, the description still adds meaning by explaining how to obtain the award_id from siblings and detailing the type enum values. This goes beyond the schema's 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 clearly states the tool lists child contracts and task/delivery orders under an IDV award. It uses a specific verb ('list') and resource ('child awards'), and distinguishes from sibling tools like usaspending_get_award.

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 when to use the tool (to get child awards of an IDV) and how to obtain the required award_id from sibling tools. It does not explicitly state when not to use it, but 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the agent knows it's a safe read operation. The description adds the ID format and cross-referencing context but doesn't disclose additional behavioral traits like error handling or rate limits. This is adequate but not rich, as annotations carry most of 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?

Three sentences, no unnecessary words, front-loaded with the core purpose. Every sentence adds essential information: what the tool does, how to get the ID, and optional scoping. Excellent structure.

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 (3 parameters, output schema exists), the description covers all needed context: ID format, scoping, cross-references, and recipient levels. It is complete for an agent to correctly select and invoke the tool without additional documentation.

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 baseline is 3. The description adds significant value for recipient_id by explaining its format (UUID with level suffix) and source (from other tools). For award_type and fiscal_year, the description largely restates the schema, but the overall addition crosses the threshold to 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 states the tool fetches a recipient's full profile with specific fields (address, business type, parent org, alternate names, total award amounts). It distinguishes from sibling tools like usaspending_search_recipients (search) and usaspending_get_award (award details), using specific verbs and resource.

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 states when to use (fetch recipient profile), how to obtain the required recipient_id (from usaspending_search_recipients or usaspending_get_award), and explains the ID format (UUID with level suffix). It also mentions optional scoping (fiscal year, award type) and cross-referencing with SAM.gov and SEC EDGAR, providing complete 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 indicate readOnlyHint=true, idempotentHint=true. The description adds behavioral detail: it lists data for the current fiscal year and specifies the fields returned, which is valuable beyond the 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?

Two sentences: first defines purpose, second provides usage guidance. No redundancy, front-loaded with key information.

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 (no required params, two optional enums, output schema exists), the description sufficiently covers what the tool does, what it returns, and how it fits with sibling tools. No 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 coverage is 100% and both parameters have descriptions in the schema. The description does not add extra parameter semantics beyond mentioning sort fields indirectly. 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?

Description specifies the exact data returned (toptier codes, agency slugs, budget authority, obligation totals) and the time frame (current fiscal year). It distinguishes itself from siblings by highlighting that its outputs are required inputs for other tools like usaspending_get_agency.

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 says 'Use this as the entry point for agency navigation' and explains that outputs are needed for agency-based filters. Does not state when not to use it, but the context of sibling tools implies it is for top-tier agencies.

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 readOnly, openWorld, idempotent. The description adds meaningful behavioral details: returns ranked summaries, specific fields, award type code groupings with constraint (cannot mix groups), date format requirement, earliest data limit, and DoD publication lag. These go beyond what annotations provide.

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: 5 sentences, no fluff. It front-loads the main purpose and filters, then provides output hints, award type guidance, date format, data limits, and a specific caveat. Every sentence serves a purpose.

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 (11 parameters, nested objects, sibling tools, output schema present), the description covers all essential aspects: what it does, filters, output includes IDs for companion tool, award type rules, date constraints, data range, and a timing caveat. No gaps are apparent.

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%, but the description adds crucial semantics: explains award type code meanings and grouping rules (mixing causes 422 error), specifies ISO 8601 date format, earliest valid date, and DoD lag. For location_filter, it clarifies using FIPS codes and geocoding. This is rich context 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 clearly states 'Search federal awards' and lists many filters, specifying it returns ranked award summaries with IDs for use with usaspending_get_award. This differentiates it from sibling tools like usaspending_get_award by indicating it's the search counterpart.

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 when to use this tool (to search awards) and hints at a companion tool (usaspending_get_award) for full details. However, it does not explicitly exclude use cases or compare with other search tools like usaspending_search_recipients.

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 as true. The description adds behavioral details: return fields (account numbers, names, managing agencies, budgetary resources) and pagination parameters (page, limit). 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 without waste: first states purpose, second details returns and links to get tool, third links to agency list tool. Every sentence is informative and 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?

Given the presence of output schema and annotations, the description covers the tool's functionality, return values, and integration with sibling tools. It is complete and actionable for an AI agent.

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 each parameter described. The description adds meaning beyond schema by explaining return fields and linking agency_identifier to usaspending_list_agencies. It provides useful context for parameter usage.

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 specifies verb (list and keyword-search), resource (federal accounts), and criteria (by agency identifier or title keyword). It distinguishes from sibling tools usaspending_get_federal_account and usaspending_list_agencies, making the purpose clear and unique.

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 when to use this tool (to search/list accounts) and when to use alternatives: usaspending_get_federal_account for full budget detail and usaspending_list_agencies for agency codes. This provides good usage context, though it doesn't explicitly 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds value by disclosing that partial matches are supported, that results include recipient level codes (P, C, R), and that IDs are UUID hashes. 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?

Description is four sentences, each adding distinct value: purpose, return data, cross-tool usage, and recipient level explanation. Front-loaded with the main action. No redundancy or waste.

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 (search with filters), the presence of annotations and output schema offloads behavioral and return-value documentation. The description fills gaps: explains recipient level codes, cross-tool integration, and partial matching. This is a complete and helpful definition.

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% with descriptions for all parameters. The description adds that keyword supports partial matches and that award_type filters total amounts, but these are already implied in the schema. Schema does the heavy lifting, 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?

Description clearly states the tool searches for recipients by name or UEI, specifies returned data (IDs, amounts, classifications, location), and distinguishes from sibling usaspending_get_recipient by noting that IDs can be passed there. The verb 'Search' and resource 'recipients' 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?

Description explains that the tool can be used to get recipient IDs for use with usaspending_get_recipient, providing a clear workflow. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, though the differentiation is 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 declare readOnlyHint, openWorldHint, idempotentHint, so the description does not need to repeat them. It adds value by stating the output includes 'top items with obligation amounts,' revealing ordering and data content. This behavioral detail complements the annotations well.

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 concise sentences with no redundancy. The first sentence immediately states the core function, the second adds purpose and output details, and the third provides cross-tool usage. 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?

Given the tool's complexity (aggregation with multiple dimensions and filters) and the presence of an output schema, the description is complete. It covers purpose, usage, output behavior, and chaining. Nothing essential is missing for an agent to select and invoke this 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 baseline is 3. The description adds context for the 'category' parameter by listing examples from the enum, and mentions chaining for NAICS. However, it does not elaborate on page, limit, or filters beyond what the schema provides, so it barely exceeds the baseline.

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 'aggregate' and clearly defines the resource 'federal spending grouped by a specific dimension.' It lists the supported dimensions (NAICS, PSC, agency, CFDA, recipient), which distinguishes it from sibling tools like usaspending_search_awards (which returns individual awards) and usaspending_spending_over_time (time-series).

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 states the tool is 'useful for trend and breakdown analysis' and provides actionable guidance to 'Chain NAICS codes into usaspending_search_awards filters or usaspending_autocomplete lookups.' This tells the agent when to use this tool and how to connect results with siblings, leaving no ambiguity.

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, idempotentHint. Description adds context about data aggregation and input format requirements, but no contradictions or additional behavioral traits beyond what annotations imply.

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 focused sentences: purpose, usage guidance, and input format requirements. No redundancy and 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?

Despite output schema existing, the description covers purpose, usage, and format constraints. The misleading FIPS guidance slightly detracts, but overall complete for a geographic aggregation tool with good annotations.

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 all parameters. However, the description mentions 'geographic filters accept FIPS codes and 2-letter state abbreviations' but the input schema has no such parameter; this is misleading. Adds confusion rather than clarity.

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?

Clearly states it aggregates federal spending by geography (state, county, district) and lists specific use cases (per-capita analysis, regional comparisons, mapping). Distinguishes from siblings by focusing on geographic breakdown.

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 tells when to use (geographic aggregation) and what not to do (avoid place names; use FIPS codes/state abbreviations). Provides actionable steps: resolve names via geocoding, chain with Census data.

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 provide readOnly, openWorld, idempotent hints. Description adds behavioral context: returns per-period totals and optional breakdowns by award category (contracts, grants, etc.), and defaults to contracts if no award_type_codes provided. 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?

Three sentences, no fluff. Front-loaded with primary action. Every sentence adds value: what it does, how to filter, what it returns.

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 existing, the description covers key output elements (per-period totals, breakdowns). Could mention data availability or pagination, but adequate for a read-only, idempotent 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 100% description coverage for all 3 parameters. The description adds overall context (e.g., 'trace spending trends') but does not add significant meaning beyond what the schema already provides. 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?

Clearly states the tool fetches aggregated federal obligation amounts grouped by fiscal year, quarter, or month. The verb 'Fetch' and resource 'obligation amounts' are specific. Distinguishes from siblings like spending_by_category or spending_by_geography by focusing on time groupings.

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?

Implied usage for time-series spending analysis with filters, but no explicit when-to-use or when-not-to-use compared to siblings. Does not mention alternatives or limitations.

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