get_cost_breakdown

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavioral context beyond that: shared billing tables cause unfiltered queries to return identical account-wide totals, only the environment holding the export needs billing_export_table set, and other environments return an error naming the proper one. This explains real operational behavior rather than restating 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 front-loaded with the main purpose, then explains the critical billing-export caveat, then lists parameters. Every sentence adds necessary information; none is filler or redundant with the schema.

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 five-parameter read-only tool with no output schema, this description covers everything needed to call it correctly: defaults, parameter semantics, configuration prerequisites, cross-environment behavior, and error handling. It also warns about the all_projects total being non-environment-specific, preventing a likely misuse.

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 0%, so the description carries the full burden, and it succeeds. It documents every parameter with meaningful details: group_by's allowed values, days' lookback basis, limit's ordering by highest net cost, all_projects' account-wide behavior and pairing advice, and environment's role and default.

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 opening sentence states a specific verb and resource: 'Summarize recent spend from the BigQuery billing export.' The description further clarifies scope by contrasting environment-project-only reporting with account-wide reporting, distinguishing this tool from nearby billing and recommendation 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 provides clear context for when to use the tool and how to behave in common configurations: by default it reports only the selected environment's project, all_projects switches to account-wide totals, and non-exporting environments error with the name of the exporting one. It does not explicitly name sibling tools as alternatives, 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.