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

With readOnlyHint/destructiveHint/openWorldHint already covering the safety profile, the description adds substantive behavior: nested-workflow recursion ('a step that is itself a workflow uses that workflow's roll-up unless it has its own estimate'), the meaning of coverage, and the unpricedRoles edge case where time counts but cost does not. These are non-obvious computation semantics an agent could not infer from annotations or schema.

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 output spec is front-loaded and the caveats follow in a logical order, so an agent can parse intent from the first sentence. The prose is dense with em-dashes and parentheticals, but every sentence carries content (recursion, coverage, unpriced roles, interpretation). Slightly heavy, but no 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?

There is no output schema, so the description carries the return-value burden and does so: it enumerates the metric families, the low-high range format, per-step shares, gates, coverage, and unpricedRoles. What it does not sketch is the top-level response shape or how per-run vs per-month sections are organized, a modest remaining gap for a six-parameter analytical tool.

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 is 3. The description restates 'at' and 'variantId' in prose ('at reads the estimates as of a date; variantId rolls up one variant'), which is roughly equivalent to what the schema already documents, and adds no syntax or default detail beyond it. It does not compensate for anything, but nothing is missing either.

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 clause gives a precise spec of the resource and its output: per run and per month, hands-on minutes, waiting minutes, labor cost, and hard costs as ranges with per-step shares and gates. It is unmistakably the cost/time rollup rather than the step list or learning tools. It never names a sibling explicitly, so it stops short of the 5 bar of differentiating itself from compass_workflow_steps or caliper_flow_performance.

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 gives reporting rules ('always say how much of the total rests on estimates before quoting it, and never present a range as one number') and interpretive direction ('where the waiting dwarfs the hands-on time... is usually where the improvement is'). What is missing is explicit routing: nothing says when to call this versus compass_workflow_steps, compass_flow_performance, or compass_workflow_learning. Usage is implied rather than stated.

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