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

Beyond the readOnlyHint/idempotentHint annotations, the description adds critical behavioral context: the server is authoritative for arithmetic, the tool never forecasts hires, and it returns a forwardable plain-text memo meant for an approver rather than the current user. This goes well beyond what annotations alone convey and prevents misuse.

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?

Three sentences with no filler: the first states the core output, the second gives usage timing and audience context, the third explains the authoritative-computation boundary. Every sentence carries actionable weight and is front-loaded.

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 tool with 8 parameters, no output schema, and a consequential business-decision purpose, the description explains what it returns, when to use it, what to avoid, and how it fits the conversation flow. Nothing an agent needs to select and invoke it correctly is missing.

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 100%, so the baseline applies. The description does not add parameter-specific guidance beyond mentioning the 'basket' (item_ids) and 'package' (preset_id), but the schema already documents each parameter fully. It neither improves nor harms parameter understanding.

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 opens with a specific verb+resource mapping: 'Turns a composed basket into the argument that gets it approved,' then enumerates concrete outputs (recruiter-fee equivalence, break-even hire count, cost per room, approval_memo). It clearly distinguishes itself from siblings by positioning itself before request_offer and disclaiming hire forecasting.

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 trigger conditions ('whenever money, ROI, justification or "I need to convince my CFO/CTO" comes up'), an explicit alternative ('before request_offer'), and a strong exclusion ('Never compute this arithmetic yourself'). This leaves no doubt about when to select this tool over its siblings.

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