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

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses the iterative protocol, the fact that Stackcut stores call arguments for recommendations, and detailed data-handling behavior: what is stored (hashed account keys, no billing sources, no IPs) and what must never be sent. This adds substantial behavioral context the annotations do not cover.

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 trigger condition and input options, then flows into the iterative loop and privacy caveats. The final privacy sentence is long but carries necessary behavioral disclosure. Overall it is dense and efficient with little wasted wording.

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 no output schema, the description still sketches the return shape ('the few missing facts that would change the answer, ranked by what's at stake, each with where to find it') and the termination condition (status is 'enough'). It covers input choices, constraints, and storage behavior, making it sufficient for an agent to invoke the 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 the baseline is 3. The description adds useful semantics by clarifying that the manifest is an alternative to the vendors+team_size pair, and by constraining acceptable values ('Send counts, prices, feature and job names only'). This goes beyond the schema's individual 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 starts a baseline stack audit, surfacing missing facts that would change the decision. Phrases like 'Start here' and 'call again until status is enough' signal its entry-point role and distinguish it from later steps. However, it does not explicitly name sibling tools such as audit_stack, so differentiation relies on 'baseline' and 'start here' rather than direct comparison.

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?

Provides explicit when-to-use triggers: 'when the user wants to cut spend across several tools, consolidate apps, or replace one tool safely, and the bills alone won't decide it.' It also specifies input options ('vendors and team_size (or a stack manifest)'), the iterative loop, and the handoff to next.tool with next.arguments. This is comprehensive guidance for selecting and driving the tool.

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