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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing data provenance (City public correction letters) and, crucially, the denominator — 'shares are of permits that went to correction' — which prevents misreading the metric.

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?

Two compact sentences: the first states scope and source, the second pins down the metric definition. No filler, and the most misreadable detail is front-loaded before the agent invokes it.

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?

An output schema exists, so return values need not be explained, and the description covers subject, source, and metric semantics. The remaining gap is how the three optional filters shape the result, which is not addressed anywhere.

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 only 33%: zone has an example, subtype has an enum/default but no explanation, and limit has only bounds. The description mentions no parameters at all, so it does not compensate for the gap — e.g. nothing says what zone does when omitted or how limit affects the returned categories.

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 names a specific resource (common plan-review corrections on Seattle ADU permits) and what is returned (share of permits per category plus cited code). It is distinctive enough to separate it from sibling lookups like get_permit_rule_details, though it never names an alternative explicitly.

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?

Usage is only implied — an agent can infer this is for diagnosing frequent ADU correction categories. There is no statement of when to prefer it over get_permit_rule_details, check_permit_requirements, or resolve_permit_submittals, and no exclusions.

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