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

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description's job is to add context — and it does: percentiles are linear interpolation, open proposals are never mixed into completed-stay statistics, every figure carries its n, and the board history has known gaps that are stated in the answer. These methodological caveats are exactly the kind of trust-relevant detail an agent cannot get from annotations.

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 purpose and reasonably tight for the amount of information packed in, but it is delivered as three very long, comma-chained sentences where the overview metrics, the number mode and the flow view blur together. A reader must re-parse to separate the modes, so structure is adequate rather than efficient.

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 burden of describing returns — and it does, covering the overview funnel statistics, the single-proposal history, and the flow view separately, plus caveats about n, gaps and interpolation. Given the tool's analytical complexity, this is close to complete, with only sibling routing left uncovered.

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 genuinely enriches both parameters beyond the schema: for number it enumerates the returned history (every column stay with date and mover, waiting state with reason, first response, votes, steps back), and for view "flow" it lists the weekly open/voting/approved/closed counts and backlog. That is meaning the schema's one-line parameter descriptions do not convey.

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?

States a specific verb and resource: it derives the Canton Dev Fund proposal lifecycle from board column history, with a concrete metric inventory (funnel counts, median/p90 days per column, time to decision, time to first human response, waiting states, bot labels, steps back). The scope is unmistakable and analytically distinct from sibling tools like get_dev_fund_activity or list_stuck_proposals, but it never names those alternatives, so sibling differentiation is left implicit.

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 does tell the agent how to use the two modes ("Pass number for one proposal", "Pass view 'flow' for the weekly ... counts"), which is real invocation guidance. However, it gives no explicit when-to-use/when-not-to-use versus the many adjacent dev-fund and proposal siblings, so routing guidance 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.