sms_status

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

With no annotations, the description carries the full burden, and it does disclose two useful facts not in the schema: the call is free (no billing) and orderId doubles as the credential/secret. It still omits whether the code persists, what happens before the SMS arrives, or any rate/polling behavior.

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?

Short and front-loaded with the verb, but '(free)' is duplicated verbatim, wasting the little space available and signaling careless editing rather than deliberate concision.

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?

No output schema, no annotations, and a single undocumented param. The description does not say what comes back (the code string? a status object?), whether the code may be absent, or how errors surface — all of which an agent needs for a polling-style lookup tool.

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?

One parameter at 0% schema description coverage, so the description must compensate. It does explain the key semantic that orderId 'acts as the secret' (credential, not just an identifier), but gives no format, length, or source guidance for the value.

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 specific verb and resource: 'Retrieve the verification code of an order.' This is distinguishable from sms_order/sms_cancel in intent, though it never names a sibling and the name sms_status is slightly at odds with 'retrieve the code' (status vs. code value).

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?

No when-to-use guidance, no mention of alternatives like sms_order or sms_rental_messages, and no hint that this is typically polled after ordering. The '(free, orderId acts as the secret)' note is about cost/auth, not usage context.

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