Agent Broker

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

Even with annotations present, the description adds substantial behavioral context: async execution via call handle requiring poll of get_outcome, compliance consent enforcement per jurisdiction, B2B-only restriction, idempotency-key retry semantics, cost, and latency. No contradictions with the annotations were found.

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 clear sections (WHEN TO USE, WHEN NOT TO USE, COST, LATENCY, EXECUTION) and is front-loaded with the core purpose. Each section contributes selection or invocation-relevant information, and the redundancy is minimal and reinforcing.

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 tool with 8 parameters, an async execution model, and no output schema, the description is remarkably complete: it explains expected return via get_outcome, cost, latency, compliance gate, and the boundary conditions against sibling tools. An agent has what it needs to select and call this 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 coverage is 88%, so the schema already explains most parameters. The description adds illustrative plain-language objective examples and mentions structured extraction, but it does not deeply define smb_id, business_phone, country_code, or extract_fields beyond the schema, which is acceptable given the high 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 first sentence names a specific verb+resource ('Place a conversational voice-AI phone call to a business') and the return type ('structured answer'). It also differentiates from siblings by emphasizing it is for businesses with no API and no booking page, making its role distinct from import_booking_url and schedule_appointment.

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 WHEN TO USE and WHEN NOT TO USE sections are explicit: use for businesses with only a phone number, do not use when a booking URL exists (and names the alternatives), do not use for consumers, and do not use for marketing. This gives an agent unambiguous selection criteria.

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 only signal non-read-only/non-idempotent/non-destructive; the description adds concrete behavioral detail: it stores a lead in AgentBroker's store, deduplicates on (smb_id, phone or email), costs $0.05/call, ~600ms latency, and requires get_outcome to retrieve the result. This materially exceeds the annotation safety profile.

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?

Well structured with core behavior first, followed by example, when-to-use, and operational metadata. No filler; each section (example, exclusions, cost, latency, execution) earns its place.

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 nested-object tool with no output schema, the description supplies routing guidance, a full invocation example, side-effect location, cost/latency, and a pointer to get_outcome for results. Nothing an agent needs to decide or execute the call 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 description coverage is ~50%, with source, idempotency_key, and consent_record_id already documented in the schema. The description compensates for undocumented fields with a concrete example mapping smb_id, name, phone, and email, and clarifies the dedup semantics of smb_id/phone/email. Minor gap: it does not illustrate notes or service_interest, but those are optional and inferable.

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 action ('Structured intake of a prospect into an SMB's funnel') and clarifies this is AgentBroker's lead store, not a CRM write. The deduplication key and validation behavior add further specificity and distinguish it from sibling operations like schedule_appointment.

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, including a named alternative: confirmed bookings should use schedule_appointment. Also excludes bulk list imports, giving an agent clear routing criteria.

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 readOnly/idempotent annotations, it discloses that the tool does NOT fetch the URL, is free, and runs in ~20ms, and it explains what it only inspects rather than guarantees. These are important behavioral traits that annotations alone do not convey.

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 headers and front-loaded summary, but it contains minor redundancy such as 'free'/'instant' repeated in both the opening and COST/LATENCY sections. Still, every major section adds actionable 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?

There is no output schema, but the description lists the returned fields (platform, smb_id, channels, country), the supported/un-supported decision, cost, latency, and workflow integration. An agent has enough context to call it correctly and interpret the result.

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 single url parameter is already fully documented in the input schema with format examples, so the description adds little beyond reinforcing the same sample URLs. This is the baseline for high 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 precise verb+resource ('pre-flight check for a booking URL') and states exactly what it classifies and returns, differentiating it from import_booking_url and verify_business. It also names sibling tools as fallbacks in WHEN NOT TO USE.

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 includes explicit WHEN TO USE / WHEN NOT TO USE sections with concrete conditions, alternatives (find_business, call_business), and exclusions. Example user queries demonstrate the exact call sequence, so an agent knows precisely when to invoke 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 mark read-only/idempotent/non-destructive, and the description reinforces this with 'NO message is sent and NO state changes.' It adds extra behavioral context: gate re-runs at send time so legal=true is not permanent, compliance_receipt is Ed25519-signed and offline-verifiable, and consent is evaluated elsewhere for voice.

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?

Well-structured with an upfront summary followed by examples, WHEN TO USE/WHEN NOT TO USE, and cost/latency. Slightly longer than strictly necessary due to two example queries and repetition of 'free' and '~15ms' in both prose and headers, but every major section earns its place.

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 6-param tool with no output schema, the description covers invocation context, return behavior (legal true/false, cited rule, remediation, receipt), exclusions, cost, and latency. An agent has everything needed to decide when to call it and what to do with the result.

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% and each parameter already has a rich description. The tool description adds little beyond example call arguments and the general (recipient, channel, message_type, content) tuple, so it doesn't materially raise the baseline.

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 opening sentence names a specific action ('pre-flight for the compliance gate'), the exact regulations covered, and preview mode. It explicitly contrasts with send_message and call_business, so an agent can distinguish it from siblings without opening 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?

WHEN TO USE spells out concrete triggering conditions (marketing tag, US SMS/10DLC, EU/UK GDPR, Canadian CASL, uncertain content) and the guard pattern before send_message/call_business. WHEN NOT TO USE explicitly excludes voice recording consent and says it never delivers anything, and references check_booking_link as the analogous de-risking 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 mark the tool read-only, idempotent, and non-destructive. The description adds meaningful context beyond those annotations: it is free, works with any valid X-Agent-Identity token, returns tier='anonymous' for keyless callers, and includes cost and latency information. 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 well-organized with a clear opening, example queries, usage guidance, and cost/latency sections. It is slightly longer than necessary because the three example user queries are near-duplicates and 'free' is mentioned both in the body and in COST, but this is minor 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?

Given there is no output schema, the description fully enumerates what the agent can expect: used operations, remaining operations, daily limit, tier, and reset time. It also covers authentication, anonymous behavior, cost, and latency, making the tool complete for a zero-parameter read-only call.

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 fully covers the input surface. With 0 params, the baseline is 4, and the description appropriately focuses on output and usage behavior rather than parameter details.

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 states the tool 'Returns the caller's current quota state' and enumerates the exact fields: operations used, remaining, daily limit, tier, and reset time. This distinguishes it from sibling tools, none of which are quota-focused, so an agent can confidently separate it from business-action 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 includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It tells the agent to call at session start or before write batches, not on every invocation, and explains that quota is already injected into write-tool responses. This is strong routing guidance with a clear alternative.

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 provide readOnlyHint=false, idempotentHint=false, and destructiveHint=true, which the description does not contradict. The description adds genuinely useful behavioral context beyond the annotations: COST ($0.2/call), LATENCY (~2000ms), and especially EXECUTION: async_by_default with instruction to use get_outcome for the result. However, it never explains the irreversible/destructive aspect flagged by destructiveHint=true (what handing off permanently changes), so it doesn't fully leverage the annotation signal.

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 one-sentence core purpose is front-loaded, followed by clearly labeled sections (example, when to use, when not to use, cost, latency, execution) that each earn their place. It is longer than the minimal get_calls example, but every section adds decision-relevant information rather than filler, and the headers make it scannable.

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 moderately complex tool (5 params, nested context object, no output schema), the description covers the core action, the context bundle contents, when to use it, and how to retrieve the async result via get_outcome. Since there is no output schema, the description need not explain return values. The main gap is that the destructive implications and per-parameter semantics are not elaborated, but the overall usage picture is sufficiently complete for an agent to call this 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 only 20% (only idempotency_key has schema-level docs), so the description carries the burden for the other four parameters. The example call demonstrates smb_id, reason, context, and priority usage in a realistic structure, which is helpful, but it does not explain the meaning of each parameter beyond what the schema enumerations already show. The context object's nested fields are left entirely to the schema. The example partially compensates for the coverage gap but not fully.

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 ('Hand off') and resource ('an in-flight task to a human operator'), plus the makeup of the context bundle (transcript, prior actions, identifiers, recommended next step). This clearly distinguishes escalation from siblings like call_business or send_message, which perform automated actions. It stops short of explicitly naming a sibling to differentiate against, so it doesn't reach a 5.

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 WHEN TO USE / WHEN NOT TO USE sections give explicit conditions ('after channel-fallback exhaustion', 'requires human judgment', 'customer has explicitly requested human contact') and an explicit exclusion ('Do not use as a first resort... only after automated resolution attempts'). This is strong guidance, though it frames alternatives by condition rather than by naming specific sibling tools, so it falls just below the top tier.

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 this read-only and idempotent, and the description adds crucial non-obvious behavior: the network is small and mostly sample data, demo entries are named [DEMO] and flagged is_demo, so the agent must check that field before acting. This goes beyond the safety profile in 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?

The description is longer than average but well organized: what it does, critical demo-data warning, examples, usage boundaries, and cost/latency all earn their place. The minor example error and slightly repetitive availability-window mention in the schema keep it from being perfect.

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 6-parameter nested-object tool with no output schema, the description plus schema covers invocation, the most critical data-quality caveat, and the alternative for real availability. It does not explain ranking criteria or the shape of results beyond is_demo, but enough is present for an agent to select and 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?

Three worked examples map natural-language requests to vertical, location, and capability values, which helps a lot. However, price_band, max_results, and radius_miles receive no real explanation beyond their names/defaults, and the 'dentists in London' example incorrectly uses capability 'plumbing'. Schema coverage is only 50%, so the description does not fully compensate.

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 concrete operation ('return ranked candidate businesses') on a specific resource (our supply network) and lists the filtering criteria. It also distinguishes this lookup from directory browsing and from situations where a specific SMB is already known, which separates it from sibling verification/calling 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?

It explicitly says to call this before schedule_appointment or send_message when no specific SMB target exists, and gives a WHEN NOT TO USE block covering general browsing and already-verified identifiers. That is concrete routing guidance, not just an implied use case.

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 readOnlyHint=true and destructiveHint=false; the description goes beyond by revealing the no-key/cost-free operation, ~300ms latency, the 10-second polling restriction, and the guarantee that replies are matched exactly to the caller's thread. No statement contradicts 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?

The description is front-loaded with a one-sentence capability summary, then uses labeled sections (examples, when to use/not, cost, latency) so an agent can scan quickly. Every section carries operational information; 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?

Despite having no output schema, it tells the agent what it will get back (state, messages, reply count) and how to use identifiers via examples. It also covers auth/cost and polling behavior, leaving no essential decision unresolved.

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 three parameters are already documented in the schema (100% coverage), so the baseline is 3. The description adds value by marking conversation_id as preferred, showing two concrete valid call shapes, and reinforcing that reference is scoped by business_number.

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 opens with a specific verb and resource — 'Read a two-way conversation thread you started' — and lists concrete return contents (state, every message, reply count). This clearly differentiates it from broadly named siblings like get_status and get_outcome.

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 gives an explicit trigger: poll after send_message with on_behalf_of returns a conversation_id. It also gives a rate-limit constraint under WHEN NOT TO USE, but it does not name alternative tools for cases that don't match, so it is a 4 rather than a 5.

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: it is free and requires no key, has ~50ms latency, and returns 'full result with cost and reason codes.' This gives the agent practical expectations beyond the annotation flags.

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 clear sections: purpose, WHEN TO USE, WHEN NOT TO USE, COST, LATENCY. Every line adds useful information and the key trigger condition 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?

For a simple one-parameter read-only tool, the description covers the essential retrieval condition, the prerequisite tool, cost, latency, and what the return value contains. With no output schema, this is sufficient for an agent to invoke it correctly in the intended flow.

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 for the one required parameter, operation_id. It never explicitly explains where operation_id comes from or its format; it only implies it is tied to a get_status call. Given low schema coverage, this is a meaningful gap.

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 states a specific action ('Retrieve'), a specific resource ('final OutcomeReceipt'), and a precondition ('completed operation'). It differentiates itself from get_status by indicating it returns the full result after status is known, so an agent can tell the tools apart.

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 and WHEN NOT TO USE are explicit and actionable. The description names get_status as both the prerequisite and the alternative for pending/executing operations, leaving no ambiguity about sequencing.

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, covering safety. The description adds valuable behavioral context: cost ('free - no key required'), latency (~50ms), and a strict polling rate limit (10 seconds). These are not implied by annotations and give the agent critical operational constraints, enhancing transparency well beyond the structured hints.

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 exceptionally well-structured and front-loaded. The core purpose is in the first sentence, followed by clear WHEN TO USE / WHEN NOT TO USE sections, then terse COST and LATENCY lines. Every sentence carries essential information with no wasted words, making it easy to parse quickly.

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 single-parameter read-only poll tool, the description provides all necessary context: what it does, when to use it, constraints on usage, and performance characteristics. The absence of an output schema is mitigated since the description implies it returns the current state. Nothing critical is missing for an agent 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 only parameter is operation_id, and the schema provides zero description (coverage 0%). The description mentions 'by operation_id' but does not explain what an operation_id is, where to obtain it, or its format. Since the schema is silent, the description should compensate, but it merely restates the parameter name without adding semantic meaning. This is a minimal gap that could confuse agents unfamiliar with the async operation workflow.

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 states the tool queries the state of in-flight async operations by operation_id. It uses a specific verb ('Query') and resource ('state of any in-flight async operation'), which distinguishes it from siblings like get_outcome (which likely returns final results rather than in-flight status). No ambiguity about what it 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?

The description includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It directs the agent to use it for polling when no webhook callback has arrived and warns not to poll more than once per 10 seconds, pointing to webhook delivery as the real-time alternative. This is exemplary usage guidance.

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 sparse annotations, the description discloses that opt-outs are recorded durably, that nothing else is auto-executed, and that execution is async with results retrieved via get_outcome. It also includes cost and latency, giving the agent a clear operational picture before calling.

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 its core purpose and then organized into terse, labeled sections covering examples, usage boundaries, cost, latency, and execution mode. Every section earns its place, and there is no redundant 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 7-parameter asynchronous tool with no output schema, the description covers selection criteria, execution mode, result retrieval, and cost/latency well. It stops short of describing the suggested_action return shape and some optional parameter semantics, but it provides enough for a correct first call.

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 only 29%, so the description needed to compensate. It does illustrate the three required parameters (smb_id, inbound_channel, raw_message) in a concrete example and maps channel types to real-world inbound sources, but sender, received_at_iso, and routing_rules receive little or no additional semantic guidance.

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: 'Classify an inbound message on behalf of an SMB and get a recommended next action,' and it enumerates the intents it handles. It also explicitly states that nothing else is auto-routed or auto-executed, which clearly separates this tool from action-oriented siblings.

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 explicit WHEN TO USE and WHEN NOT TO USE sections, covering inbound triage channels and excluding outbound communications and unverified compliance-flagged lists. It also includes a concrete example query-to-invocation mapping, making both selection and first-call construction unambiguous.

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 supply idempotentHint=true, and the description reinforces it with 'Idempotent — calling twice returns the same smb_id.' It additionally discloses cost ('free'), latency (~600ms), and the requirement for an email-verified key, which are not in the annotations. No contradiction exists. The description adds useful behavioral context beyond the structured hints.

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?

Though detailed, the description is well-structured with clear sections (purpose, examples, WHEN TO USE, WHEN NOT TO USE, cost, latency) and front-loads the primary purpose. Every section earns its place, and the examples are concise and directly relevant. The length is justified given the complexity and the multiple decision points it clarifies.

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 covers the tool's purpose, usage conditions, idempotency, cost, latency, platform constraints, and integration with sibling tools (schedule_appointment, send_message, capture_lead). It states the return value (smb_id) explicitly. There's no output schema, but the description covers everything an agent needs to invoke the tool correctly, making it complete for its complexity.

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% — every parameter has a description in the input schema. The tool description adds marginal value such as example verticals in the user query illustrations, but it doesn't introduce new semantics beyond what the schema already explains. Per the baseline for high coverage, a 3 is appropriate.

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 defines the tool's purpose: turning any supported public booking URL into an smb_id for downstream use. It names the specific action (import) and resource (booking URL) and explicitly contrasts with find_business when only a business name is given. The intended output (smb_id) is also stated, making it distinct from siblings like check_booking_link or capture_lead.

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 'WHEN TO USE' and 'WHEN NOT TO USE' sections provide explicit conditions, including example user query patterns and the exact circumstances to avoid (e.g., business name only, unsupported websites). It names the alternative (find_business) and even references /supply/platforms for allowed hosts. This is exemplary guidance for an agent to decide between tools.

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 valuable behavioral context: free/no-key access, USASpending.gov source, data coverage 2020-2026, sorting by award amount, and ~1200ms latency. It doesn't disclose possible API errors or edge cases, but that is a minor gap for a simple read-only lookup.

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 its core purpose and organized into labeled sections. The example queries are somewhat lengthy but serve as useful few-shot call patterns for an agent. Each section—WHEN TO USE, WHEN NOT TO USE, COST, LATENCY—earns its place, though it could be trimmed slightly.

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 two-parameter lookup with no nested objects and no output schema, the description is complete: it states the source, input requirements, example calls, returned fields, constraints, and alternatives. An agent has everything needed to invoke the tool and interpret results 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 input schema already provides 100% coverage with clear descriptions for both parameters, including max_results default/min/max and sorting behavior. The description's examples add practical value by mapping natural-language queries to company_name values, but they don't meaningfully extend the parameter semantics 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?

The description opens with a specific verb and resource: 'Search US federal contract awards by company (recipient) name using the free USASpending.gov public API.' It clearly lists the returned fields and scope, and the WHEN NOT TO USE section explicitly distinguishes it from sibling tools like verify_company_record and screen_sanctions.

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 a dedicated WHEN TO USE section with concrete use cases (supplier due-diligence, vendor qualification, competitive intelligence) and an explicit WHEN NOT TO USE section naming alternatives and exclusions (non-US, state/local, sanctions screening). This gives an agent unambiguous guidance on tool selection.

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 this readOnly, idempotent, and non-destructive, and the description adds substantial behavior beyond that: product is never checked, reason_code can be 'partial' but never 'clear', and no tariff rate or restricted status is ever fabricated. Also discloses cost, latency, and that it acts as a middleman over multiple sanctions lists.

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 each section earns its place: the critical product-classification limitation is front-loaded, examples show realistic queries, and WHEN TO USE / WHEN NOT TO USE are clearly separated. The structure makes it easy for an agent to scan and extract the right 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?

With no output schema present, the description comprehensively explains what the tool returns: restriction findings, destination risk levels, HS hints, tariff guidance links, and party screening results. It also covers failure semantics like 'partial' reason codes and 20-party call splitting, plus cost and latency, making it complete for a complex 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?

Schema coverage is 100%, so the baseline is 3, but the description adds important functional meaning: product is only echoed and never classified, hs_code is not derived, destination_country is checked against the embargo map, and parties are screened against three named sanctions lists. These clarifications go beyond the schema's field descriptions.

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 precise verb and resource: cross-border trade screening of the destination and parties, explicitly excluding product classification. Clearly distinguishes itself from an export-control clearance by saying it never checks the product against any list.

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?

Contains explicit WHEN TO USE and WHEN NOT TO USE sections, instructing use as a pre-flight check before quoting or shipping and excluding domestic shipments, authoritative tariff rates, or licensed export compliance reviews. This leaves little ambiguity about when an agent should select 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?

Beyond annotations, the description discloses a valuable failure mode: if no mint secret is activated, it returns an honest not_configured failure rather than a key. It also reveals that the endpoint is immediate, requires no human action, issues only free-tier keys at 100 ops/day, and costs no key to call—useful context annotations do not provide.

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 clear sections and front-loaded purpose, but it is slightly redundant: the opening paragraph and WHEN TO USE both cover the autonomous-agent-without-email condition. The example and operational details earn their place, though a tighter edit would reduce repetition.

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 4-parameter tool with no output schema, the description is remarkably complete: it covers when to use, when not to use, the HMAC proof requirement, the not_configured failure branch, cost, latency, and an example call. An agent can confidently select and invoke this tool without additional information.

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 input schema already covers all four parameters at 100%, so the baseline is 3. The description adds value by including a full example invocation with concrete values for agent_id, timestamp, nonce, and signature, and by pointing to where MACHINE_MINT_SECRET is documented.

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 action and resource: 'Agent self-serve API key issuance' and clearly distinguishes it from ordinary key-request flows by describing the autonomous, secret-proving mechanism. It also differentiates from sibling tools by scoping to free-tier agent self-provisioning without a human email inbox.

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 explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections, naming the exact alternative (the human email flow at /keys/request) and excluding paid-plan usage. It also tells the agent to call once and branch on the not_configured failure, which is concrete operational guidance.

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 readOnly/idempotent/non-destructive annotations, the description adds valuable behavioral context: it returns estimates only, does not execute the operation, gives exact or ranged prices depending on channel/outcome, does not promise accuracy percentages, and is free/no-key with ~100ms latency. No annotation contradiction.

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 organized into examples, usage guidance, and operational notes. Every section adds necessary information, and the structure makes it easy for an agent to parse quickly.

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 preview tool with no output schema, the description covers return value shape (cost, latency, success probability, exact vs. range), parameter usage via examples, usage constraints, caching guidance, cost, latency, and key requirements. An agent has enough context 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 coverage is only 50% (operation lacks a description), but the description compensates with two concrete examples showing operation values ('send_message', 'schedule_appointment') and params shapes ('preferred_channel'). It also clarifies that params is 'the same request body you would pass to the operation', adding meaning beyond the raw 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 states a specific verb ('Return') and resource: expected cost, latency, and success-probability estimates for a proposed call before execution. It clearly distinguishes the tool from operational siblings by framing it as a pre-execution estimation step, and clarifies exact vs. range pricing.

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 (budget constraint, deciding whether to proceed) and WHEN NOT TO USE (hot loop, cache for 60 seconds), plus concrete example queries. It does not name alternative tools, but the usage boundaries are clear and actionable.

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 meaningful runtime behavior: routing through the SMB's native booking system with fallback to voice AI or web form, async execution via get_outcome, and cost/latency characteristics. It does not detail side effects beyond cancellation, and the mention of 'hold' and 'confirm' is not reflected in the action enum, but the added behavioral context is substantial.

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 longer than average but well structured with labeled sections: examples, WHEN TO USE, WHEN NOT TO USE, COST, LATENCY, and EXECUTION. The main purpose is front-loaded, and the sections earn their place by giving practical invocation and routing context. A small amount of redundancy exists, such as the verified smb_id requirement appearing more than once.

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 provides strong operational context: prerequisites, alternatives, cost, latency, and async behavior. However, there is no output schema and the description does not explain the result shape, what availability lookups return, or how nested objects like requested_time and customer should be populated. For an 8-parameter tool with nested objects, this leaves noticeable gaps despite the otherwise rich context.

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 only 25%, so the description needed to compensate, but it only lightly does so. The examples map three natural-language requests onto smb_id, action, and service, yet the reschedule and cancel examples omit the required existing_appointment_id parameter. There is no guidance for requested_time, customer, notes, or how the action enum values relate to the full request flow.

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 opening line clearly names the resource (appointments with an SMB) and lists concrete actions such as book, reschedule, cancel, and check availability. The example queries reinforce what the tool does in practice. It is slightly less crisp than a single-purpose tool because it is an umbrella for several appointment operations and does not explicitly distinguish itself from siblings like check_booking_link or call_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?

The description includes an explicit WHEN TO USE section and a WHEN NOT TO USE section that names alternatives: find_business and verify_business. It also warns against bulk scheduling and emphasizes the verified smb_id prerequisite. This gives the agent clear decision rules for selecting this tool over alternatives.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond them: the UN list is intentionally excluded for licensing reasons, lists_screened may vary per call, reason_code becomes 'partial_screening' on partial failure, and screening_status must be branched on instead of matched. It also discloses the compliance_receipt signing and the no-fabrication guarantee.

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?

Though detailed, the description is well-structured with headers, examples, and explicit cost/latency fields. Every section earns its place by addressing a real invocation risk: partial screening, false-clear semantics, and source attribution. The most decision-critical warning (never treat matched:false as clean) 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?

With no output schema, the description fully carries the burden of explaining return values and failure modes: it names screening_status values, matched, matches structure, lists_screened, sources_unavailable, reason_code, and compliance_receipt. It also covers cost, latency, and response verification. Nothing an agent needs to call and interpret this tool 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 description coverage is 100%, so baseline is 3. The tool description adds value by showing exact example mappings from natural-language queries to parameters and reinforces the country parameter's annotate-never-filter behavior, which prevents an agent from incorrectly using country as a hard filter.

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 ('Free screening of a name or entity against official sanctions lists') and names the exact lists screened (OFAC, EU, UK). It is unmistakably distinct from generic tools like check_compliance by scoping the behavior to sanctions-only screening.

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' (onboarding, payments, vendor engagement, due diligence) and 'WHEN NOT TO USE' (not a substitute for full KYC/AML, not bulk screening, not a compliance clearance). It even gives concrete example user queries and their corresponding parameter mappings, leaving no ambiguity about when to invoke 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 readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond those: the exact number of checks, the fact that it does not probe individual tools, cost, latency, and a rate-limit warning. No contradictions 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 front-loaded purpose, followed by example, usage guidance, cost, and latency. Every section adds decision-relevant information with no 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 zero-parameter health probe with strong annotations, the description is complete: it explains what is checked, what the result means, when to call it, when not to call it, and operational characteristics. No output schema exists, but 'reports how many passed' is adequate for this simple 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?

There are zero parameters, so the schema imposes no semantic burden. The description reinforces the empty call with 'call self_test({})' in the example, which is sufficient; no deeper parameter explanation is needed.

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 ('Service health probe: runs 6 internal checks and reports how many passed') and explicitly distinguishes this from checking individual tools. It clearly says what the tool does and what it does not do.

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' guidance covers startup, high-stakes sequences, and error recovery. 'WHEN NOT TO USE' gives a concrete rate-limit constraint, and the 'does NOT probe each tool individually' statement helps route agents away from incorrect use.

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 a state-changing, non-idempotent operation, and the description builds on that with a non-bypassable compliance gate, consent rejection behavior, channel fallback, cost/latency, and sync_fast with get_outcome retrieval. It discloses more behavioral context than any structured field provides.

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 example queries, WHEN TO USE/WHEN NOT TO USE, and cost/latency/execution sections. It earns most of its length; a small amount of compliance warning is repeated.

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 complex, state-changing tool with no output schema, the description covers send scenarios, exclusions, cost, latency, and result retrieval. The absent consent_record_id in the schema and lack of guidance on the remaining enum choices keep it from being 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 only 63%, and the description compensates with concrete example mappings (user utterance to recipient/content/preferred_channel) and explains the marketing restriction and message_type intent tagging. However, it repeatedly references consent_record_id as a required input while the schema exposes no such parameter, which is a real usability gap.

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 opens with a specific verb+resource ('Send a message') and then narrows scope: channels (WhatsApp/SMS/email/voice), actor (agent's user or SMB), and five message types. It also differentiates itself from send_transactional_confirmation in the negative guidance, so an agent can tell this tool apart from its sibling.

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?

Contains an explicit WHEN TO USE section with five concrete scenarios and a WHEN NOT TO USE section with the specific sibling (send_transactional_confirmation), the compliance rule for marketing, and a ban on bulk/cold outreach. This is the strongest possible usage guidance.

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 and the schema's idempotency_key says retries are not re-executed/re-charged, while the annotation idempotentHint=false indicates the operation is not idempotent; this is a direct contradiction. The useful fallback and honest-failure details cannot overcome that conflict.

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 tool description is structured with example, when-to-use, cost, latency, and execution sections; the key routing guidance is front-loaded. It is slightly repetitive about not using marketing, but no major wasted content.

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?

It covers channel fallback behavior, honest failure, idempotency semantics, cost, latency, and how to retrieve the result via get_outcome. It is reasonably complete for a side-effectful send tool, though the invalid example and the idempotency contradiction leave some ambiguity.

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 40%, so the description needed to clarify the parameters, but its example uses recipient.id_type/id_value while the schema requires recipient.phone_or_email. It also uses business_name in the example while the schema's data description says smb_name for booking_confirmation, creating ambiguous guidance for constructing the payload.

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 specific resource (transactional confirmations) and enumerates concrete types: OTPs, booking confirmations, payment receipts, cancellation notices. It clearly separates this tool from conversational messaging, and the example query reinforces the intended use.

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 state that this tool is for messages that must be delivered reliably and must not be used for marketing or conversational messages. Sibling differentiation is implied through the exclusions and transaction-specific examples.

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 meaningful context beyond annotations by stating that the tool does not contact the business and by providing cost (free, no key) and latency (~500ms), which helps an agent decide to invoke 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?

The description is front-loaded with the core behavior and then uses labeled sections (example, when to use, when not to use, cost, latency). Every section adds decision-relevant information with no filler or repetition.

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 having no output schema, the description states what the lookup returns (contact channels, capabilities, last verified), when to call it, when not to call it, cost, and latency. This is sufficient for an agent to select and invoke 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 coverage is 0%, but the description compensates with a worked example mapping smb_id and capability_to_verify to concrete values, and the 'WHEN TO USE' text explains capability_to_verify as a confirmed-capability check. It doesn't explicitly define the exact smb_id format or the optionality behavior, but the example and context make parameter usage clear enough.

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 action and resource ('Look up what we know about a business in our supply network') and lists the returned data (contact channels, capabilities, last verified). It adds a sharp disambiguation ('DIRECTORY LOOKUP - it does not contact the business') that separates it from call_business, but it does not explicitly differentiate from the similarly named sibling verify_company_record.

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 'WHEN TO USE' and 'WHEN NOT TO USE' sections give explicit conditions with a concrete example: use before communications/scheduling for unverified identifiers or confirmed capability, and avoid when find_business returned the SMB within 24 hours because it is already verified. It names the alternative tool find_business, 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it states the tool never fabricates results, returns an honest 'not_found' with which sources were queried, and discloses cost and latency. This behavioral disclosure is not covered by 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 reasonably long but well-structured with clear headers (introduction, examples, when to use/not, cost, latency). It front-loads the core purpose and uses concrete examples that add value without excessive rambling.

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 tool with only 3 simple parameters and no output schema, the description is exceptionally complete. It specifies the registries, return fields, not_found behavior, source transparency, cost, latency, and usage patterns. An agent has all necessary information 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?

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it restates parameter purposes and provides usage examples, but does not offer deeper semantic detail (e.g., how to combine parameters, precedence rules). The examples illustrate but do not significantly enrich parameter understanding.

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 specifies the verb 'verify' and resource 'company record', and it details the exact registries queried and fields returned, making the purpose unambiguous. It does not explicitly differentiate from the sibling tool verify_business, though the focus on GLEIF/SEC and LEI distinguishes it implicitly.

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?

Includes dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections with concrete scenarios (contract signing, vendor qualification) and exclusions (private companies, KYC). It does not name alternative tools, but the guidance is explicit and actionable.

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