SMS and WhatsApp Messaging

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral context: preview mode sends nothing, makes no state changes, incurs no cost, re-runs at actual send time, and produces an Ed25519-signed offline-verifiable compliance_receipt. No contradiction with 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?

The description is long but every section earns its place: purpose, examples, when to use, when not to use, cost, and latency. Key differentiators are front-loaded in the opening sentences.

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?

Despite no output schema, the description explains what the tool returns (legal decision, exact rule, remediation, signed receipt) and covers failure/edge cases. Combined with the full input schema and annotations, 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 description coverage is 100%, so the schema already fully documents all six parameters. The examples and prose reinforce usage but do not add new parameter-level semantics beyond what the schema 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?

The description names a precise verb and resource: a compliance pre-flight that runs the same gate as send_message/call_business but in preview mode. It explicitly contrasts itself with those siblings and with check_booking_link, so an agent can distinguish it immediately.

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 has dedicated WHEN TO USE and WHEN NOT TO USE sections with concrete triggers (marketing, US SMS/10DLC, EU/UK GDPR, Canadian CASL, uncertain content) and explicit exclusions (not for recording consent, not a substitute for send_message). It also tells the agent how to act on legal=true vs legal=false.

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 and idempotentHint, so the description is not needed for basic safety. It adds substantial behavioral context: the network is small and mostly sample data, demo entries are named [DEMO] and flagged is_demo, and availability_window is accepted but not applied and the response carries availability_window_applied: false. No contradiction with annotations exists.

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 detailed but well-organized and every section earns its place: core function, critical demo-data warning, example mappings, explicit usage rules, and operational notes. Important caveats are front-loaded before the examples and when-to-use guidance.

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?

Given the tool has no output schema and non-trivial nested parameters, the description covers the essential invocation context, demo-data caveat, and non-applied availability_window semantics. It could go slightly further by describing the shape of a ranked result beyond the is_demo flag, but the guidance is sufficient for an agent to call and interpret results correctly in most cases.

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?

Although schema coverage is only 50%, the description's example queries add concrete mappings from natural-language requests to JSON arguments for vertical, location, and capability. The schema already explains availability_window's non-applied behavior and provides defaults/constraints for max_results and radius_miles; remaining params like price_band are self-explanatory from their schema structure.

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 action and resource: 'return ranked candidate businesses from our supply network' given explicit criteria. It also distinguishes itself from a general directory/browsing tool and from tools like verify_business by explicitly ruling out use when a verified SMB identifier is already held.

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 provides both explicit WHEN TO USE and WHEN NOT TO USE guidance, along with three example user queries mapped directly to call arguments. It names alternatives such as schedule_appointment and send_message and states conditions for preferring them, leaving little to inference.

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=true, destructiveHint=false, and idempotentHint=false; the description adds valuable context by promising that replies are matched exactly and never guessed, so the data belongs to the end-user. Costs and latency are also disclosed. No contradiction with 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?

The description is well-structured with distinct sections: overview, examples, WHEN TO USE, WHEN NOT TO USE, cost, and latency. The core purpose is front-loaded and each section earns its place with actionable information, though the example queries add some length.

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 tool with three well-described parameters and no output schema, it adequately states what data is returned, when to call it, and a rate limiting caution. It doesn't detail return structure or errors, but gives the agent enough to select and use 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 fully documents each parameter. The description contributes a usage example and notes conversation_id is preferred, but it does not add substantial meaning beyond what the schema already says about reference, business_number, and conversation_id.

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 starts with a specific verb and resource: 'Read a two-way conversation thread you started,' and enumerates exactly what it returns: state, every message exchanged, and reply count. This clearly differentiates it from siblings like get_status or get_outcome because it is uniquely about conversation threads.

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?

An explicit WHEN TO USE section states it should be called after send_message returns a conversation_id, in order to poll for the business's reply. The WHEN NOT TO USE section adds a real constraint: don't poll more often than every 10 seconds. It doesn't explicitly recommend an alternative sibling, but the trigger condition is concrete and sufficient.

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, so safety is covered. The description adds useful non-safety behavior: free/no key required, ~50ms latency, and that the result includes cost and reason codes. No contradiction with 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?

Every sentence earns its place: purpose, usage conditions, cost, and latency are each given a labeled line. The description is short and front-loaded with the core action.

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 simple one-parameter read-only tool, the description covers purpose, when to use, cost, and latency. It partially covers return contents (cost and reason codes), and since there is no output schema, a bit more detail on the OutcomeReceipt shape would make it fully complete.

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 0%, and the description does not explicitly explain operation_id beyond naming it. The WHEN TO USE section indirectly implies it comes from get_status, but the parameter format/source is left to inference, so the description does not fully compensate for the missing schema coverage.

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 and resource: 'Retrieve the final OutcomeReceipt for a completed operation.' It clearly distinguishes this from get_status by framing it as the follow-up that retrieves the full result once status reaches success/failure/partial.

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?

Explicit WHEN TO USE and WHEN NOT TO USE sections name get_status as the alternative and state the exact state condition. This leaves no ambiguity about when the tool should be invoked.

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, so the safety profile is covered. The description adds useful behavioral context beyond annotations: polling rate limits, cost, latency, and the requirement that the operation be in-flight.

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 tightly structured with labeled sections: purpose, when to use, when not to use, cost, and latency. Every sentence contributes operational guidance, and the core purpose is front-loaded.

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?

Given the single parameter, rich annotations, and simple polling use case, the description covers the main operational concerns: usage context, throttling, cost, and latency. It does not enumerate possible status values or error behavior, but the core information needed to call and poll is present.

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 schema provides only a bare operation_id string with no description, and the description adds that it identifies an in-flight async operation. This is some added meaning, but it does not explain how to obtain the operation_id, expected format, or what qualifies as a valid pending operation.

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 and resource: 'Query the current state of any in-flight async operation by operation_id.' This clearly distinguishes the tool from siblings like get_conversation or get_outcome by scoping it to async operation polling rather than business entities.

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 provides explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, including the polling frequency cap and the webhook alternative for real-time updates. This gives an agent actionable decision criteria for selecting this tool over other mechanisms.

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 mark the tool as read-only, idempotent, and non-destructive; the description adds behavior beyond that by explaining exact vs min/max pricing and explicitly disclaiming an accuracy guarantee ('does not promise an accuracy percentage - check cost_range'). It also states cost and latency characteristics, which the agent would otherwise have to discover by calling it.

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?

Information is front-loaded and segmented into examples and usage rules, with each section earning its place. Despite covering behavior, examples, when/not-to-use, and cost/latency, it avoids redundancy.

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?

Even without an output schema, the description tells the agent what the response contains (cost estimate, latency, success probability, exact vs range, cost_range caveat) and how to invoke it with both required parameters. The inclusion of examples, caching guidance, and operational characteristics makes it a complete quick-reference for correct invocation.

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 schema describes params as 'the same request body you would pass to the operation' but leaves operation undefined. The description compensates with concrete examples mapping user intent to operation and params values. It still doesn't enumerate valid operation names, so the agent must rely on context or other operation knowledge.

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 ('Return') and names the three outputs (cost estimate, latency estimate, success-probability estimate) for a proposed call before execution. It also clarifies exact vs range pricing, so the agent knows what kind of answer to expect. This clearly differentiates it from execution-oriented sibling tools like send_message.

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?

WHEN TO USE explicitly ties the tool to budget-constrained decisions before any operation. WHEN NOT TO USE warns against hot-loop calls and gives a concrete cache duration of 60 seconds. This is direct guidance with no reliance on inference.

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 indicate read-only, idempotent, and non-destructive behavior, but the description adds valuable context: it runs 6 internal checks, reports pass count, does not probe each tool individually, has ~200ms latency, is free, and has a rate-limit caution. No contradictions with annotations; description enriches them substantially.

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 main description is front-loaded with the essential purpose, and each additional section (example, when to use, when not to use, cost, latency) earns its place by helping an agent decide and call correctly. No filler or redundant repetition of schema data.

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?

Given no parameters, no output schema, and rich annotations, the description is fully complete. It explains what the tool checks, how to call it, when to use it, and its operational constraints, so 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?

The tool has zero parameters, so the schema already covers everything. The description adds an example call 'self_test({})' and clarifies that no arguments are needed, which is sufficient for this parameterless tool.

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: 'runs 6 internal checks and reports how many passed,' and explicitly distinguishes itself from sibling tools with 'it does NOT probe each tool individually.' This makes it immediately clear what self_test does and what it does not.

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?

Provides explicit WHEN TO USE guidance: 'at agent startup, before high-stakes task sequences, or after receiving unexpected errors,' and a clear WHEN NOT TO USE constraint: 'Do not call more than once per minute in production.' Also gives a matching example user query, leaving no ambiguity about appropriate invocation.

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?

The description goes well beyond the basic annotations (readOnlyHint=false, destructiveHint=true): every send passes a non-bypassable compliance gate, marketing without consent is rejected with a compliance_violation receipt, channel selection is abstracted with automatic fallback, future scheduling more than 2 minutes out is refused, and execution is sync_fast with results fetched via get_outcome. These behavioral traits materially shape how an agent should invoke the tool and are not present in the annotations. No contradiction exists.

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 long but well-structured with labeled sections (EXAMPLE USER QUERIES, WHEN TO USE, WHEN NOT TO USE, COST, LATENCY, EXECUTION) and front-loads the core function. Most sections earn their place, though the compliance gate is described twice and the 'free during launch' phrasing may age poorly. For a tool with this compliance complexity, the length is largely justified rather than bloated.

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?

Given 8 parameters, nested objects, no output schema, and significant compliance constraints, the description is thorough: it covers acceptable use, forbidden use, cost, latency, execution mode, and failure behavior (compliance_violation receipt), and points to preview_cost and get_outcome for follow-up. The primary gap is the missing consent_record_id in the schema despite the description making it essential for marketing sends, which creates actionable confusion for the agent.

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 63%, so the description must add semantic value, and it does: it explains message_type intent and the consent requirement for 'marketing', clarifies that preferred_channel can be 'auto' with channel fallback, and documents send_at_iso as unsupported/refused. The two example invocations map real parameter values to user queries. However, the description references a consent_record_id that is not present in the input schema, leaving the agent uncertain how to supply it, and some parameters (template_id, template_vars, idempotency_key) rely solely on schema descriptions. It compensates meaningfully but not completely.

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 pair ('Send a message on behalf of an agent's user or an SMB across WhatsApp... SMS, email, or voice'), enumerates five message types, and includes concrete example invocations. It also implicitly distinguishes itself from send_transactional_confirmation by explicitly excluding OTPs/critical transactional confirmations, leaving no ambiguity about what this tool does.

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?

There are dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections. The former lists five concrete scenarios (booking confirmation, replying to a customer, follow-up, reminders, opted-in marketing); the latter explicitly names send_transactional_confirmation for OTPs/critical confirmations, forbids un-consented marketing, and excludes bulk/cold outreach. This is exactly the explicit when/when-not/alternatives guidance the dimension asks for.

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?

The description claims idempotency ('Idempotent transactional messages') and details 24-hour replay semantics, but the annotation idempotentHint is explicitly false. This is a direct contradiction. The description does add useful behavioral context (channel fallback, honest failure, cost, latency, execution model), but the contradiction mandates a score of 1.

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 well-organized with labeled sections and front-loaded intent, making it easy to scan. It repeats 'Do not use for marketing' in both WHEN TO USE and WHEN NOT TO USE, and the example/schema mismatch detracts, but overall structure is strong.

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?

The description includes cost, latency, execution mode, and points to get_outcome for retrieving results, which helps compensate for the lack of an output schema. However, the idempotency contradiction and the mismatch between the example and the input schema leave important gaps in an agent's ability to call 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?

With only 40% schema description coverage, the description needed to compensate, but its example uses recipient.id_type/id_value while the schema requires recipient.phone_or_email, and data.business_name while the schema example mentions smb_name. These conflicting field names mislead rather than clarify, so the description adds little positive value beyond 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?

The description clearly identifies the tool's scope by enumerating concrete message types (OTPs, booking confirmations, payment receipts, cancellation notices) and distinguishes it from marketing/conversational messaging. It relies somewhat on the tool name for the verb, but the example query and 'MUST be delivered reliably' phrasing make the purpose unambiguous.

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 explicitly provides WHEN TO USE and WHEN NOT TO USE sections, stating when it is appropriate ('MUST be delivered reliably') and when it should not be used (marketing, promotional, conversational). This clearly routes the agent away from siblings like send_message.

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 establish read-only/idempotent/non-destructive behavior. The description adds value by stating the tool performs no external contact, lists the kinds of data returned, and notes that no key is required. There is no contradiction with the readOnlyHint.

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, then uses compact labeled sections for example, usage, cost, and latency. Every section adds decision-relevant information without redundancy.

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 two-parameter read-only lookup, the description covers what the tool returns, when to call it, when not to call it, and even cost/latency. No output schema exists, but the description gives enough return-value context for an agent to act.

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 0%, so the description must compensate. It provides one clear example mapping a user request to smb_id and capability_to_verify, but it does not formally define the expected values or optionality of capability_to_verify beyond 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?

Description begins with a specific verb and resource ('Look up what we know about a business in our supply network'), clarifies it is a directory lookup that does not contact the business, and includes a concrete example query. This makes it easy to distinguish from the contact-oriented siblings and from find_business.

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?

Explicit WHEN TO USE and WHEN NOT TO USE sections give actionable selection criteria, including the exact condition under which find_business should be used instead (results returned within last 24 hours). This is stronger than typical usage guidance.

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