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

The description shoulders the entire behavioral burden since annotations expose only readOnlyHint=true, and it delivers: hidden-by-default coverage, the exact contrast between hidden vs. down-weighted clusters, the nuanced fitFlag semantics ('treat them as comparison-content candidates at best, never headline opportunities'), and the non-obvious normalizing side effect that 'coverage filtering, dismissing, excluding, or fit-flagging can shift the relative numbers of other clusters'. This last insight about score drift is exactly the kind of subtle behavior an agent could not infer from code or 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?

The description is unusually information-dense without being terse — every sentence earns its place. It leads with the one-sentence definition, then progresses deliberately through filters, state-driven exclusions, fit handling, and the normalization caveat. A wall of text, but skipping it would cost the agent genuine planning capability.

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 tool this complex — 7 parameters, 2 enums, cross-tool state coupling, relative scoring — the description addresses nearly every non-obvious behavior: defaults, hiding rules, score normalization, and fit-flagging semantics. Only minor gaps remain: the cursor pagination and activeMetaCluster filtering are never mentioned, and they aren't self-explanatory from names alone. The total 0.9 must be split across the 4 coefficients carefully, so 3.7 rounds to 4.

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?

With 0% schema description coverage, the description carries full parameter documentation burden. It explains `goal` and `coverage` (including the hidden default ["gap","partial"] and the 'covered' opt-in semantics, which no schema-derived source could convey). Given the deliberately rich write-up of the goal and coverage parameters, a 4 is the right ceiling — it does not over-explain the already-inferable numeric parameters.

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 sentence — 'List content opportunity clusters sorted by opportunity score' — is a model verb+resource statement that names exactly what the endpoint does and how output is ordered. It's clearly differentiated from siblings like get_opportunity_detail through the rich behavioral detail, though it never explicitly names the sibling it is not the way the top calibration example does.

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?

The description references sibling mutations (set_opportunity_status, set_excluded_terms) and explains their causal effect on this list — dismissed clusters are hidden, excluded terms down-weight scores — which tells the agent precisely how this tool composes with its siblings. It also documents the default coverage behavior (["gap","partial"]) and the 'refresh candidates' workflow. It stops short of an explicit when-not-to-use or a pointer to get_opportunity_detail for drill-down needs, but the context is genuinely clear.

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