sms_numbers_read

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing that rental_available reports whether rental is offered per country and that search_available queries externally rentable inventory — context that explains the open-world hint. It omits any note on pagination or result size limits for search.

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 core purpose and the sibling disambiguation are front-loaded in the first two sentences, then actions are listed in a scannable pipe-delimited form with zero filler. The repeated "Needs: agentId" phrase three times is mild redundancy that could be consolidated, but nothing is padded.

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 5-action, 8-parameter multiplexed tool with no output schema, the description covers every action and every required parameter pairing, which is the critical information for correct invocation. It does not characterize return shapes (number lists vs. analytics payloads), which is a real gap given the absence of an output schema, but not one that blocks correct selection.

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 50% (agentId, areaCode and locality have no schema descriptions), but the description compensates: it ties agentId to the three agent-scoped actions and describes search_available as "filtered by country / area code / digits", implicitly covering country, areaCode and contains. locality and the compact/full mode are left to the schema, which keeps it below a 5.

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 opens with a specific verb+resource ("Read the SMS numbers of an agent and search numbers that can be rented") and immediately disambiguates from the sibling voice tool: "Voice phone numbers are in get_agent_phone." The action enumeration further pins down the full capability surface, so an agent can distinguish it from sms_numbers_write and get_agent_phone without opening any 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?

Each of the five actions is given a one-line meaning plus its requirement ("Needs: agentId"), which tells the caller exactly which condition selects which branch. The voice-vs-SMS pointer to get_agent_phone is an explicit alternative. It stops short of stating exclusions for the write path (sms_numbers_write) or prerequisite permissions, so it is clear but not fully exhaustive.

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