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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds genuinely new context: results are 'descriptive — recorded status and fields, never causal inference,' free tier returns only met + headline with a US sample, full tier adds per-dimension evidence, and omitting all params returns a usage hint.

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?

Effectively one dense but front-loaded paragraph that leads with purpose and sibling differentiation, then enumerates the three modes, then the output semantics and tiering. No sentence is filler; em-dash clauses carry the routing and return-shape information compactly.

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, the description carries the return-shape burden and does so for all three modes plus tier differences and default behavior. Combined with annotations covering the safety profile, an agent has everything needed to invoke it correctly.

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 baseline would be 3, but the description goes further: it explains what each mode actually produces (pivot one dimension across every actor with met status and basis; side-by-side D1–D7 comparison; the dimension_watch fields of actor, dimension, current vs expected_change, trigger, timeline) and encodes the mutual-exclusivity constraint that additionalProperties:false alone does not express.

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?

Opens with a specific verb and resource ('Query the Sovereign Capability Profile (SCP) register') and immediately distinguishes itself from get_actors, which 'fetches whole actors' and is 'where energy_context is served; it is not returned here.' An agent can route between the two without opening either 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?

States the selection rule explicitly — 'Pass exactly one of' — and gives the condition that selects each mode: dimension pivots across actors, actors compares D1–D7, watch:true switches to the dimension_watch register. It names the alternative sibling (get_actors) and what that sibling does differently.

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