usa_agency_overview

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

The annotation readOnlyHint=true already indicates a safe read operation. The description adds minimal behavioral context by mentioning 'budgetary resources and obligations' but does not describe response format, data granularity, or any caveats. This is acceptable given the annotation coverage, but no extra transparency is provided.

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 front-loaded, with a single sentence stating the purpose followed by a helpful list of common codes. No wasted words or redundant information. It is appropriately structured 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?

The description is adequate for a simple 2-parameter read-only tool, but it lacks an explanation of the response structure (since there is no output schema) and does not clarify how this overview differs from other USAspending tools that appear in the sibling list. The mention of 'budgetary resources and obligations' gives a hint, but more context would help.

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 both agency_code and fiscal_year documented. The description adds a few more common agency codes (e.g., '012', '015') beyond those in the schema, but this is marginal. The fiscal_year parameter is only described in the schema, not in the description, so the description adds little semantic value 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 the tool's function: 'Get an overview of a federal agency's spending, including budgetary resources and obligations.' The verb 'get an overview' and the resource 'federal agency's spending' are specific. It is somewhat distinct from siblings like usa_spending_by_agency, but the name and title 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?

No guidance is provided on when to use this tool versus similar alternatives such as usa_spending_by_agency or usa_spending_over_time. The description only lists common agency codes, which is parameter guidance rather than tool-selection guidance.

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