get_budgets

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the data returned (limits, spent amounts, periods) and explains pagination via 'limit' and 'offset' parameters. However, it does not explicitly state that the operation is read-only, nor does it describe default sorting, authentication requirements, or any side effects. The 'Get' verb implies safety, but the description lacks depth beyond that.

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 efficiently structured: a one-line summary followed by a compact parameter list. Every line provides necessary information without redundancy. The 'Args:' block is clearly organized and scannable, making it easy for an agent to parse.

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 list tool with an output schema and optional filters, the description is nearly complete. It explains the tool's purpose, return content, and all filter parameters. Minor gaps include lack of default sorting order and mention of how filters combine, but the presence of an output schema reduces the need to describe return values. Overall, it provides enough context for 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?

The schema has 0% coverage, so the description must compensate. It does so effectively by explaining each of the 7 parameters with filter semantics, including prefix operators for 'name' (eq., contains., contains-i.) and date filtering examples for 'created_at' and 'updated_at'. This adds significant meaning beyond the schema's type/default information. It would be a 5 if it covered all possible filter operators, but it gives enough examples to be highly useful.

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 'Get all budgets with their limits, spent amounts, and periods.' This is a specific verb + resource combination that unambiguously identifies the tool's function and distinguishes it from sibling tools like get_accounts or get_categories. The added detail about what data is returned solidifies 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 implies usage through the phrase 'Get all budgets' and the filter parameters, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions. For example, there is no guidance on when to use get_budgets instead of other listing tools. This makes the usage context implied rather than explicit.

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