utilpeek: parse and format a phone number (numbering-plan check)

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds the traits annotations cannot carry: 422 errors are not charged, 'valid' means numbering-plan conformance only (not assigned, in service or reachable), 'carrier' is the original range holder so ports go undetected, the input is processed in memory and never logged or stored, and latency is under 0.1 s. This is exactly the extra context the lower bar with annotations calls for.

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, then routing, then caveats; every sentence carries distinct information (errors, validity semantics, privacy, cost, quota, docs). It runs long and packs pricing/quota/docs into the same paragraph as behavioral caveats, but there is little filler to cut.

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 an output schema present, return values need not be described, and the description covers what remains: cost, free-tier quota, error behavior, the precise meaning of the reported fields, privacy handling, and a docs link. Nothing an agent needs to invoke it correctly is missing.

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 would be 3, but the description goes further by explaining the interaction between the two fields: a national-form number without a region is a 422, which tells the agent why 'region' matters and when it is mandatory even though the schema marks it optional. That is real semantic value beyond the schema text.

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 concrete verb+resource ('parse and format a phone number') and immediately scopes it as a numbering-plan check, which separates it from the sibling lookup_phone_prefix. An agent can pick it over the other identifier/contact tools without opening the 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?

Names the alternative tool explicitly and the exact condition that selects it ('For a prefix's country and network use lookup_phone_prefix'), and gives a when-not boundary (a non-phone string, or a national form without region, returns 422). Routing is fully determined, not left to inference.

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