optimize_stack

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses real behavioral traits: each result line carries plan, monthly_cost_usd, calc, vendor quote, source_url, checked_at, assumptions, plus alternatives. It also states that unpublished prices are 'unknown' and are never estimated, and that manual_signup_only means a human must sign up and must never be automated — an important safety constraint.

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 purpose and the core rule ('set quantities, rest 0') are front-loaded, followed by a compact parameter glossary and return-shape notes. It is dense but every line carries information; only the trailing URL self-reference adds little for an agent.

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 9 loosely-titled parameters and no schema descriptions, the description supplies the missing semantics and explains result fields well enough that an output schema is barely needed for interpretation. The one omission is the undocumented 'mode' argument, which an agent cannot reason about from this text.

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 defines nearly every parameter in domain terms: scrape_pages vs scrape_pages_js (JS rendering), proxy_gb (residential GB/month), emails_sent, search_queries, gpu_hours (1 GPU) and gpu_model with concrete examples like 'H100'. The notable gap is the 'mode' parameter, which defaults to 'full' but is never explained.

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 outcome: the cheapest suitable stack across tracked providers for the given monthly usage quantities. It is clear what the tool returns, but it never distinguishes itself from the sibling optimize_agent_stack, which sounds nearly identical in intent.

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?

Usage is implied through the input framing ('set the quantities you need, rest 0') and the exclude_manual_signup exclusion rule, which tells the agent when plans get dropped. However, there is no statement of when to prefer this over compare_gpu_prices, compare_deals, or optimize_agent_stack, so the agent must infer routing.

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