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

Annotations only say readOnlyHint/openWorldHint; the description adds real behavioral context: it runs the same math as Hemrock's spreadsheet and was checked against the workbook, the result echoes every input used, results are monthly arrays with month 1 first, and reactivation is disabled under the cohort curve. It also discloses the quota model (no calculation when signed in; a few free runs a day otherwise) and that the response includes a webUrl to hand to the user.

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?

Structure is deliberate and front-loaded: trigger, then inputs, then the two retention approaches, then outputs, then webUrl and pricing. It is long for a description, but the tool has 17 nested inputs and two modeling modes. Some sentences restate schema defaults (months 12–120 default 48; ltvMonths 1–120 default 60), which is mild redundancy.

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 and a deeply nested single `inputs` object, the description carries the burden well: it covers required inputs, both retention modes, forecast length, and roughly what comes back (each line by month, totals, ending ARR, webUrl). The return shape is described at a summary level rather than by field, and error behavior is left to the schema's Error definition.

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, but the description adds cross-parameter meaning the schema cannot: under "Cohort curve" churn applies only to opening subscribers, reactivation is off, and the curve is indexed by months since a cohort started (month 1 usually 1, 0.8 at month 13, up to 120 values, missing months 0). It also clarifies that ltvMonths caps LTV regardless of forecast length, a distinction the schema states only faintly.

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 first sentence names a specific verb and resource — forecast SaaS/subscription revenue — and enumerates the outputs (subscribers, MRR/ARR, churn/reactivation MRR, billings, deferred revenue, LTV:CAC, CAC payback). That specificity alone separates it from ecommerce_forecast_compute, unit_economics_compute and fund_economics_compute without opening any schema.

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?

It opens with "Use when the user wants a SaaS or subscription revenue forecast" and gives an explicit routing rule inside the tool: "Use the cohort curve whenever the user describes retention by cohort or month by month." It also instructs sending only what the user supplied and flagging defaults. It stops short of naming when NOT to use it (e.g. e-commerce or generic unit economics, which have sibling tools).

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