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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, yet the description goes further by defining what each status means — notably that "unconfirmed" means handed to the SIM without phone confirmation and may have gone out, which is a real ambiguity an agent must handle. It also states that times and error details come back, and adds a safety rule against unilateral resends.

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 the action and lookup key, then the status vocabulary, then the safety caveat — no filler sentences. The parenthetical explaining "unconfirmed" is long but earns its place because that status is the one most likely to be misread.

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 one-parameter read tool with an output schema and full annotations, nothing an agent needs is missing: what to pass, what comes back in outline, what the values mean, and what not to do next. Return-shape detail is correctly delegated to the output schema.

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?

There is a single parameter with 100% schema description coverage, so the schema already explains messageId and its origin. The description restates the same idea ("by its messageId") without adding format, lookup-failure, or retention-window details, so the baseline 3 applies.

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?

Specific verb + resource: "Look up where a text ... is now, by its messageId," and it explicitly ties the input to the sibling tools that produced it (send_sms / send_sign_in_code). It even enumerates the possible status values, so an agent knows exactly what kind of answer to expect, distinguishing it from the sibling senders and from list_* tools.

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 makes the calling context clear (after a send_sms or send_sign_in_code produced a messageId) and adds an explicit prohibition against resending failed/unconfirmed texts without asking the user. There is no true alternative tool to disambiguate against, so the missing piece is minor, but exclusions are framed as post-call behavior rather than as when-not-to-use-this-tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' merely restates structured data. What the description genuinely adds is scope: the snapshot is per-account and limited to today's usage against daily limits. It does not mention how or when daily counters reset, which would have been a useful behavioral detail beyond the 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?

Two sentences, front-loaded with the resource and its contents, followed by the usage trigger and a closing safety note. Every clause carries information and 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?

An output schema exists, so the description need not enumerate return fields, and it still previews the key values (usage today, limits, remaining). For a zero-parameter read-only tool this is nearly complete; the only unstated detail is the reset/timezone semantics of 'today,' a minor gap.

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?

The tool takes zero parameters, so there is no parameter meaning to add; baseline 4 applies. The description correctly implies the scope is fixed to the caller's own account with no filtering options.

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 (show) and resource (account plan and today's usage), then enumerates the exact contents: texts and sign-in codes sent today, daily limits, and remaining count. It is clearly distinguishable from siblings like send_sms and send_sign_in_code, which perform sends rather than report capacity.

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?

Gives two concrete triggers: 'when the user asks about limits' and 'before sending several texts,' the latter implicitly routing the agent to check capacity before invoking send_sms/send_sign_in_code. It stops short of explicit when-not-use or exclusion conditions, so it is strong but not exhaustive.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), so the trailing 'Read-only' is redundant. The description still adds real context beyond the annotations: the online flag and last-seen timestamp let an agent reason about freshness before sending, and the deviceId linkage explains how the result feeds other tools.

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?

Two sentences with the resource and returned fields front-loaded, then the usage guidance. The only wasted words are 'Read-only', which merely restates the readOnlyHint annotation.

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 zero-parameter list tool with a rich annotation set and an existing output schema, nothing an agent needs is missing. It explains what is returned at a high level, why it matters, and how to use the result, without over-explaining.

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?

The tool takes no input parameters, so there is nothing to document on the input side and the baseline is a 4. The description still adds value by explaining that the returned phone ID is what other tools expect as deviceId, giving the output field a purpose.

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 ('List the Android phones linked to the user's SMSTunnel account') and enumerates exactly what each entry contains: ID, name, online status, last-seen time. That is clearly distinct from siblings like get_message_status or list_received_texts, so the agent can pick it without opening a 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?

Gives two concrete use cases (pick a phone and pass its ID as deviceId to send_sms or send_sign_in_code; verify a phone is online before sending) and names the downstream tools explicitly. This is exactly the when/when-not routing an agent needs.

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

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

Annotations already declare this is read-only, idempotent and open-world, so the safety profile is covered. The description still adds real context beyond the annotations: results come back newest-first, the sync setting is off by default, and only texts arriving after it is enabled will ever appear, which prevents an agent from misreading an empty result as 'no messages'.

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 lead sentence front-loads what is returned, and the two follow-up bullets handle prerequisites and safety. Every sentence adds information an agent would otherwise have to guess at; there is no filler.

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 read-only list tool with a full schema and an output schema, the description covers prerequisites and ordering, so it is nearly complete. The only small gap is that it does not mention the paging defaults or point to list_phones for deviceId, though the schema supplies both.

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?

All five parameters have full schema descriptions, so the schema carries the parameter documentation burden and the baseline is 3. The description only implies which filter to reach for ('filter with phone', 'since a time') and adds no syntax or default detail beyond what the schema already states.

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?

Specific verb (read) plus resource (received SMS) plus scope (what the user's phones received, newest first) plus the exact fields returned: sender, words, time, receiving phone. That wording cleanly separates it from siblings like send_sms and get_message_status, which deal with outbound traffic and delivery state.

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?

It gives concrete use cases ('see replies to texts the user sent', 'what arrived since a time') and the filter that selects each one. It also states a hard when-not condition: the key must be opted in for received texts, and the phone app must sync received texts, which is off by default.

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

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

Beyond the annotations, the description discloses important behavior: the separate sign-in allowance, strict code-format validation, character limit, one-text-per-person rule, international number requirement, and refusal cases. It also explains the return value and points to get_message_status for delivery checks.

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 front-loaded with the core purpose and the send_sms routing rule, then uses bullets for validation constraints. Despite being detailed, every sentence carries operationally relevant information for correctly invoking this tool.

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?

An output schema exists, so the description needn't detail the return structure, but it still tells the agent that a message ID is returned and to use get_message_status for delivery. Given the strict validation rules and mutation behavior, the description is complete enough to call the tool 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 description coverage is 100%, so the schema already documents all four parameters. The description still adds meaningful validation semantics for message, especially the exact digit formats that count and the formats that are refused, plus the one-number and international-format constraints for to.

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 states a specific verb and resource: send a sign-in or verification code by SMS to one phone number. It also explicitly distinguishes this from send_sms, so an agent can select the right tool without opening sibling schemas.

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?

It gives explicit when-to-use guidance: only sign-in codes, which count against a separate allowance. It names the alternative for other text (send_sms) and adds a clear exclusion against automatic resend after an error or failed status.

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

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

Adds substantial behavior beyond the annotations: offline messages queue and send when the phone reconnects, long messages split into multiple SMS parts, and the agent must never auto-resend after an error or unconfirmed status. It also names the sending device and points to get_message_status for delivery confirmation, none of which is derivable from readOnlyHint/openWorldHint/idempotentHint.

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-loads the core action and mechanism in the first sentence, then uses tight bullets each carrying one operative rule. The approval and batching bullets are long but every clause changes agent behavior; nothing reads as filler.

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 non-idempotent, open-world mutation tool this covers the risks an agent needs: consent gating, recipient scoping, rate limits, offline behavior, no-retry policy, and where to check delivery. An output schema exists, and the description correctly refrains from enumerating the return payload beyond naming the message ID.

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 is 3; the description adds only modest value, chiefly the instruction to ask the user for a country code when unsure and the format expectation for 'to'. Most other parameter detail (deviceId resolution order, defaultCountryCode fallback) is already fully documented in the schema.

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 ('Send one text message (SMS) to one phone number') and immediately explains the unusual mechanism — the user's own Android phone sends it from their own number — which distinguishes it from any gateway-based sender. Scope is unambiguous at one recipient per call.

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?

Gives explicit when-to-use rules (only texts the user asked for and the recipient expects), an exclusion routing to a named sibling ('For sign-in or verification codes, use send_sign_in_code instead'), a batching strategy with a throughput bound (~30/minute), and a concrete approval workflow before sending.

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