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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), and the description adds real behavioral context beyond them: the current rate is always user-supplied and never assumed, the arithmetic is deterministic, the method is explained, and output is computed across several efficiency-gain scenarios with stated defaults. It stops short of describing failure modes or input validation behaviour.

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?

Front-loaded with the purpose, then inputs, then returns, so an agent can stop reading early. The middle and final sentences are dense lists, but each clause carries substantive information rather than filler.

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 nested tool with no output schema, the description supplies both the input contract and a detailed enumeration of return values (revenue/profit per job and month, earnings per hour worked, full-capacity ceilings, matching package price, findings), which is what the agent needs. The missing piece is routing guidance relative to its siblings.

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 only 40%, so the description must carry more weight. It does enumerate the main conceptual inputs (cost base, rate and unit, invoiced-hours share, one to three packages with price and effort, jobs per month) and states the efficiency-gain default of 0/15/30, but it says nothing about the optional inputs (staff cost, variable cost per hour, planned utilization, currency, direct-cost pass-through, hours_per_day), leaving a real gap.

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?

Specific verb (Compare) plus a precisely bounded resource: the economics of hourly/daily billing versus fixed packages for the same work. It is clearly separable from build_packages and stress_test_package, which construct and test a package rather than compare models.

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?

Implied usage is fairly legible (compare the economics of current time-based charging against packages), but there is no explicit when-to-use versus the siblings build_packages, package_scope_language and stress_test_package, and no when-not-to-use guidance. The agent must infer the routing decision.

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