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

The annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: pagination behavior ('one page of at most 1000 records'), truncation to fit the answer, filtering limitations ('QuickBooks has no OR, cannot filter on Line fields'), and sensitive-data exclusions ('Government identifiers, birth dates and card-processing details are not available'). These go well beyond the structured 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 concise and front-loaded, with two sentences that both earn their place: one states the action and subject, the other clarifies the budget type. There is no redundant or filler 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?

Together with the rich schema and annotations, the description covers key operational constraints: pagination, truncation, filter limitations, and excluded sensitive fields. It also notes that each budget returns every BudgetDetail line. It lacks explicit return-shape detail beyond that and does not mention sibling tool routing, but for a read-only search tool with strong annotations, this is a minor gap.

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 criteria parameter's schema description is very detailed, covering operators, filter fields, and examples. The tool description itself does not add new parameter meaning beyond what the schema already provides, so 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 verb and resource: 'Search budget records in QuickBooks Online.' It also adds a defining detail ('A profit-and-loss budget with one amount per account per period') that helps distinguish budgets from other entity types. However, it does not explicitly contrast with sibling tools like get_budget or create_budget, so it stops short of full differentiation.

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?

There is no explicit guidance about when to use search_budgets versus alternatives such as get_budget or get_budget_vs_actuals. The intended use is implied by the name and the phrase 'Search budget records', but the description does not state when to choose this tool or what it is not for. The criteria parameter includes operational constraints, but not alternative routing.

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