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

Annotations already indicate read-only and idempotent behavior, but the description goes further by disclosing the return format ('hourly, monthly and whole-project ranges'), the inclusion of assumptions, and the editorial nature of the data (not real quotes). This is valuable context beyond the structured annotations and directly informs the agent how to interpret and present the results.

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 three concise sentences that are front-loaded with the tool's core function, followed by return details and usage guidance. Every sentence adds necessary information without redundancy. The structure is highly efficient for an agent to parse and act on.

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?

Given the tool's moderate complexity (4 parameters, nested roles array) and the presence of an output schema, the description provides sufficient context for selection and invocation. It covers what the tool does, what inputs are needed, what outputs to expect, and the proper use of the results. With schema and annotations handling structured detail, the description is complete.

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 input schema covers all parameters in detail (roles, weeks, region, hoursPerWeek) with clear descriptions, so the baseline is 3. The description adds minimal semantic value by referring to 'roles (discipline, seniority, headcount)' and 'optional duration in weeks' which simply maps to existing schema descriptions. It does not introduce any new parameter meaning beyond what the schema already provides.

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 uses the specific verb 'estimate' and identifies the exact resource: 'what an outsourced game team costs in USD'. It also enumerates the input types (roles, region, duration) and clearly differentiates from sibling tools like get_studio or search_studios. The phrase 'Use for "what would X cost" and budgeting questions' reinforces the tool's unique 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 gives clear context for when to use the tool: 'what would X cost' and budgeting questions. It also provides a crucial usage caution: 'These are this site's editorial market ranges... not quotes from any listed studio — present them as a budget range, never as a price.' This is strong guidance, though it does not explicitly mention alternatives or when not to use other tools.

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