Agent Broker

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

Even with annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description adds non-redundant behavioral context: execution is async via get_outcome, there is a compliance gate enforcing recording consent per jurisdiction, and it discloses cost ($0.5) and latency (~45000ms). It loses one point because it doesn't state what happens when the compliance gate blocks a call (e.g., it returns an error, alternative path) or whether the fee is incurred then.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core description is tight and front-loaded with the differentiator, followed by precise WHEN TO USE/WHEN NOT sections that are direct and scannable. It could earn 5 by removing the slight redundancy between the main paragraph and the 'WHEN TO USE' section (both mention 'no booking page/API'), but it remains efficient enough 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?

The tool has no output schema and a complex async execution, so the full burden falls on the description. It covers the async pattern (use get_outcome), the return types (transcript + extracted fields, business restrictions (B2B), exclusions (B2C/telemarketing), cost, latency, and the compliance gate — a truly complete decision =and-invocation bundle 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 86%, so the schema describes most params. The description adds critical meaning above the schema: it clarifies that smb_id and business_phone are mutually exclusive alternatives ('Provide this OR business_phone'), effectively a 'one-of' relationship not evident from the schema alone. It also explains that plain-language objective is enough because the voice AI navigates the call, and provides concrete examples of extract_fields. It matches the high-coverage baseline with an extra layer of explanation.

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 what the tool does: 'Place a conversational voice-AI phone call to a business on a consumer's behalf and return a structured answer.' It differentiates itself from siblings by emphasizing the ~60M long-tail SMBs with no API/booking page, which makes its purpose and niche unmistakable. The tool name 'call_business' is amplified by the description, not merely restated.

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 a dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' section. It explicitly names alternative tools (import_booking_url + schedule_appointment) and the condition (target has a booking URL) that routes away from call_business. It also excludes consumer calls and telemarketing, removing ambiguity about which call type this tool handles.

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 discloses key behavior beyond the annotations: it performs validation, enrichment, dedup, inserts into a CRM/pipeline, and is 'sync_fast' but requires 'get_outcome' to retrieve the result. It also adds cost and latency. This gives an agent a realistic understanding of the mutation behavior and how to obtain the outcome.

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 instruction is well structured with a one-sentence core summary, a example case, explicit usage boundaries, and additional execution/coist details. No sentence is wasted, and the most important information 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 tool with a nested prospect object, no output schema, and non-idempotent write semantics, the description is remarkably complete. It explains when to use, what happens inside (validation, enrichment, deduplication), and how to obtain results via get_outcome, making it fully workable for an AI 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?

The schema has only 33% description coverage, so the description must compensate. It does so through a concrete example mapping a natural language query to the nested 'prospect' object and smb_id, and additionally explains that consent_record_id is required when downstream send_message calls are anticipated. Some individual fields are still left to inference, but the example covers the required structure well.

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 performs 'structured intake of a prospect' with validation, enrichment, and deduplication, and inserts into an SMB's pipeline. It distinguishes itself from schedule_appointment in the exclusion guidance, so the agent can immediately understand this is for pre-booking lead capture rather than confirmed scheduling.

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 say to use it when a prospect has expressed interest and to avoid it for confirmed bookings or bulk imports. It even names the sibling 'schedule_appointment' as the correct tool for bookings, providing direct alternative routing.

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 (readOnlyHint, idempotentHint, destructiveHint false), the description discloses critical behavior: it does NOT fetch the page, is free, runs at ~20ms, only classifies the URL shape, and returns platform, smb_id, channels, and country. It also cautions it cannot confirm whether a page is currently live/available. This is substantial value beyond 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 clear sections for examples, when to use, when not to use, cost, and latency. Each section earns its place, and the most decision-relevant facts (free, instant, classification-only) are front-loaded in the first sentence.

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 classification tool with no output schema, the description is complete: it defines the input, the return semantics (platform, smb_id, channels, country), the guard-rail behavior, and the downstream decisions. The lack of a formal output schema is compensated by listing the exact semantic outputs the agent should expect.

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% and the input schema already fully documents the required 'url' param with examples. The description reinforces the URL usage through example queries, but it does not add deeper parameter semantics beyond what the schema provides, so baseline of 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 uses a precise verb 'pre-flight check ... classifies which booking platform a URL belongs to' and names the exact resource and decision it informs: whether import_booking_url will accept the URL. It clearly distinguishes itself from siblings like import_booking_url and verify_business by framing it as a free pre-flight guard, so an agent can identify 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?

Dedicated WHEN TO USE and WHEN NOT TO USE sections state exactly when to call the tool, how to act on the result (supported=true vs false), and explicitly name alternatives: import_booking_url, verify_business, find_business, and call_business. Example user queries show the full call flow, leaving no ambiguity about placement in a workflow.

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 clearly states NO message is sent, no state changes occur, and the gate is re-run at send time so a legal=true is not a permanent license. These behavioral traits go beyond the readOnlyHint/idempotentHint annotations and are consistent with them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then uses structured WHEN TO USE / WHEN NOT TO USE sections and example queries. Each sentence adds value: exclusions, limitations, free cost, ~15ms latency, and remediation behavior are all relevant for the agent's decision.

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 compliance pre-flight tool with no output schema, the description fully covers when, when not, cost, latency, idempotence, limblocks, and the fact that a legal=false returns the exact rule and remediation. Nothing critical is missing for a caller to correctly plan around this 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 description coverage is 100%, so the schema already documents all six parameters in detail. The description adds useful examples and reinforces the core gate inputs, but it does not meaningfully extend parameter semantics beyond what the schema already provides.

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: it is a 'pre-flight' compliance gate that checks whether a send would be permitted before delivery, and distinguishes itself from send_message and call_business. The analogy to check_booking_link further pins down its role as a de-risking preview tool.

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 says to call it 'the moment before send_message or call_business' for regulated sends (marketing, SMS to US, EU/UK, Canadian recipients). WHEN NOT TO USE explicitly says it is not a substitute for send_message, never delivers anything, and doesn't cover two-party voice recording consent.

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 the cost per escalation, the latency, and the async execution semantics with get_outcome needed to retrieve the result. It also clarifies the side effect of handing work to a human operator. This adds meaningful behavioral context that annotations alone 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 structured with sections for example, when to use, when not to use, cost, latency, and execution. The main behavior is front-loaded and the structure makes it scannable. The invalid example prevents a perfect score for structure because it adds misleading clutter.

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 cost, latency, async behavior, and decision criteria, which is good for an escalation tool. However, the missing parameter documentation and the invalid sample call mean an agent still cannot confidently construct a schema-valid invocation for all cases, especially the required context and priority fields.

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, but it does not sufficiently document the parameters. The example is not schema-valid: `agent_blocked` is not in the reason enum, `summary` is not an actual parameter, and the required `context` object is omitted. The prose only loosely describes some context fields.

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 object: handing an in-flight task to a human operator with a full context bundle. It clearly conveys what the tool does and is distinguishable from siblings like get_outcome or 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?

It provides explicit WHEN TO USE and WHEN NOT TO USE guidance: escalate after automated resolution failure, human judgment, or explicit customer request, and do not use it as a first resort. This tells the agent when this tool is appropriate and when it is not.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat that this is a safe read operation. The description adds valuable behavioral context: results are curated/verified/transactable, ranking happens, no raw directory results are returned, and it includes cost and latency guidance. It doesn't detail output format or ranking logic, but it goes beyond the annotation baseline.

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 purpose is stated in the first sentence, followed by compact, high-value examples and explicit usage boundaries. Every block (purpose, examples, use, not use, cost, latency) earns its place. No fluff or repetition of schema defaults is included.

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?

This is a multi-parameter discovery tool with no output schema, but the description provides enough to call it correctly: examples, criteria, usage sequencing, and constraints. It's missing an explicit statement about the returned SMB fields or how ranking is scored, but given the annotations and examples, an agent can operate confidently without that.

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 33%, so the description must compensate. It does so by explaining the high-level criteria and providing concrete examples that map user queries to JSON inputs, especially for vertical, location, and capability. However, it does not explicitly elaborate on price_band or availability_window without the schema; property names like max_usd and start_iso/end_iso are fairly self-explanatory, so the gap is minor.

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 ('find business' → 'return ranked candidate SMBs'), names the essential criteria (vertical, location, capability, price band, availability window), and explicitly distinguishes its output from raw directory results. This clearly differentiates it from siblings like schedule_appointment, call_business, and verify_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?

A dedicated 'WHEN TO USE' section explains when the tool is appropriate and even prescribes calling it before schedule_appointment or send_message. A 'WHEN NOT TO USE' section explicitly lists exclusions, such as using it as a general directory or when a verified SMB identifier is already known.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond those: it must only be called after completion, it returns cost and reason codes, and it carries known cost/latency. There is 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 compact and front-loaded with the core purpose, followed by clear usage conditions and cost/latency metadata. No filler or redundant restating of the tool name.

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 read-only tool with one parameter and no output schema, the description covers the core trigger condition, the return content, and the main caveat. It is slightly thin on error behavior or what happens when operation_id is invalid, but the usage guidance compensates.

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, but the description does not explain where it comes from or how to obtain it. Since schema description coverage is 0%, the description needed to compensate, and it only indirectly implies operation_id identifies the operation whose outcome is being retrieved.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Retrieve the final OutcomeReceipt for a completed operation.' It also distinguishes itself from the sibling get_status by clarifying that get_status is for checking state while this tool retrieves the full final result.

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 and WHEN NOT TO USE guidance, including the exact precondition ('after get_status returns success/failure/partial') and the exclusion ('Do not use for operations still in pending/executing state'). This is exemplary routing behavior.

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 and idempotent, so the description doesn't need to restate safety. It adds operational context beyond annotations: a 10-second poll interval, a webhook alternative, a cost, and approximate latency. It lacks a return-state vocabulary, so the agent'knowledge of the exact status values must come from elsewhere.

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 first sentence stes purpose immediately and is followed by short labeled guidance sections. Every line earns its place; the cost, latency, and usage boundaries are compact and directly useful with out fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only polling tool, this is quite complete: required input, when to use, when not to use, safe assumptions from annotations, and cost/latency. The only real gap is the absence of a clear state vocabulary, especially since there is no output schema to explain what statuses the tool can return.

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?

Control schema coverage is 0%, so the description must carry the parameter meaning. It does: operation_id is the identifier of the pending/in-flight async operation being polled. It doesn't say where the id comes from or its accepted format, but for a single-parameter string this is near the minimum needed for correct invocation.

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 specifies a concrete verb and resource: it queries the current state of an in-flight async operation by operation_id. It is clear and not a tautology, though it does not explicitly differentiate itself from the sibling get_outcome or mention when get_outcome would be the better choice.

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 and high-value: the agent is told to poll when no webhook has arrived, to check progress, not to poll more than once per 10 seconds, and to prefer webhook delivery for real-time updates. This is sharp, actionable routing 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 annotations, the description reveals async-by-default behavior with a pointer to get_outcome, discloses cost and latency, and clarifies that the tool enriches context and routes to handlers or escalation paths. It adds meaningful operational/behavioral detail without contradicting 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 purpose is front-loaded, with an example call and structured sections (when to use, limitations, cost, latency, execution). The structure is efficient and scannable; the erroneous example and minor missing space in the cost line are small issues in an otherwise tidy layout.

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 execution model (async via get_outcome), cost, latency, and a clear usage scope, which is good for an async tool without an output schema. However, it does not describe the shape of the retrieved result, and the provided example omits a required field, so some ambiguity remains 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?

Schema description coverage is only 17%, and the description only indirectly explains raw_message and inbound_channel. It doesn't clarify smb_id, sender, received_at_iso, or routing_rules semantics. The example is also misleading because it uses 'channel' instead of 'inbound_channel' and omits required smb_id, creating a risk of invalid calls.

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 specifies strong verbs: receive, classify, enrich, and route, with a clear resource ('inbound messages on behalf of an SMB'). It names concrete intent types (booking, cancellation, inquiry, complaint) and positions itself as the inbound-triage tool among outbound/scheduling siblings, making differentiation easy.

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 define the appropriate contexts and exclusions (inbound triage vs outbound, opt-in/compliance cases). It doesn't name a specific alternative tool as the fallback, but the distinction is clear enough for an agent to select it.

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 (idempotentHint, readOnlyHint false), the description discloses real behavioral details: $0.005 per-call cost, roughly 600ms latency, auto-detection of the booking platform, auto-extraction of business name, and the idempotent guarantee that duplicate calls return the same smb_id. It also notes that country_code is used for compliance routing in later send_message calls.

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 and front-loaded: core purpose first, then examples, then explicit WHEN TO USE / WHEN NOT TO USE, then COST and LATENCY. The three example queries overlap somewhat with the textual patterns in the usage section, creating minor redundancy, but each section still contributes clear operational information.

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 tool with only one required parameter and no output schema, the description provides enough context to invoke it correctly: it explains the pipeline order, downstream tools, supported platform categories, cost, latency, and when to avoid it. The only notable gaps are edge-case behavior for invalid/unsupported URLs and a precise description of the returned smb_id shape, but the WHEN NOT TO USE note already partially mitigates that.

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 all seven parameters are already documented thoroughly, including the vertical enum and auto-inference behavior. The description adds concrete examples of how to supply booking_url and vertical, but those examples mostly restate schema information rather than add new semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Turn ANY public booking URL ... into a callable smd_id' and names what the smd_id can be used for (schedule_appointment, send_message, capture_lead). It distinguishes the tool from siblings like find_business in a plantext WHEN NOT TO USE section, so there is no purpose ambiguity.

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 NOT TO USE sections provide concrete user patterns (e.g., 'book me at https://cal.com/...', 'reserve a table at opentable.com/r/...') and clearly route name-only business requests to find_business. It also instructs that this tool should be called FIRST and that the returned smb_id can be passed immediately to schedule_appointment.

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 it read-only and idempotent, but the description adds exact per-call cost, latency, a 5% accuracy SLO, and caching guidance. There is no contradiction with 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 the core behavior, then uses clearly labeled sections for examples, usage conditions, cost, and latency. Every section adds useful information and there is no padding.

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 names the returned estimate types, the accuracy threshold, and the tool's own cost and latency. However, with no output schema, the exact return shape is not specified, and the second example is malformed because it drops the required params key.

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 documents params as the same request body to pass to the operation, but operation has no description. The examples compensate partially by showing send_message and schedule_appointment, but the second example omits the required params key, which could mislead an agent into producing an invalid call.

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 states a concrete verb and object: it returns cost, latency, and success-probability estimates before execution. This clearly distinguishes it from sibling execution tools such as send_message 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 give explicit conditions: use before operations under a budget constraint, do not use in a hot loop, and cache results for at least 60 seconds. The example user queries make the intended invocation pattern concrete.

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 carry safe readOnlyHint=false, destructiveHint=true, and idempotence=false, so safety is largely declared. The description usefully adds that the tool routes through the SMB's native booking system and falls back to a voice AI or web form, but the tool also mentions hold/confirm actions that do not appear in the action enum, and it doesn't clarify fallback outcomes or cancellation side effects.

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 definit ion is moderately sized but well structured: it opens with the core function, then provides relevant example user-query mappings and a WHEN TO USE section. It is not overly verbose, though some trailing fragments and repeated labels add minor noise.

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?

This is a complex appointment-management tool with 7 parameters, nested objects, no output schema, and a destructive side-effect profile. The description explains basic invocation and routing but does not clarify the expected return value, confirmation/guard behavior, fallback for form, or gaps around time-format and required reschedule/cancel fields.

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 schema description coverage at only 14%, the description needs to explain most parameters, but it only shows partial examples for action, smb_id, and service. The nested fields such as requested_time, customer, and existing_appointment_id are not explained, and the example query 'next Tuesday at 3pm' does not show how that time becomes requested_time.

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 handles availability lookup, hold, confirm, reschedule, and cancel appointment actions with an SMB, and includes concrete examples. However, it doesn't distinguish itself against sibling tools such as check_export_link or import_booking_url, so it gets slight differentiation credit but not full credit.

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 explicit conditions: book/reschedule/cancel a specific appointment with a business and requires a verified smb_id. This is actionable, but there is no complete WHEN-NOT-TO-USE guidance or explicit alternative-tool selection behavior, thoughthe description indicates the verified smb_id prerequisite.

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 as read-only, idempotent, and non-destructive. The description meaningfully adds a rate limit ('Do not call more than once per minute in production'), operational latency (~200ms), and the fact that it costs nothing. It also reveals that it checks reachability and supply network size, which are non-obvious behaviors. 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 front-loaded with the core purpose and uses clear labeled sections (WHEN NOT TO USE, COST, LATENCY) so an agent can scan quickly. Each sentence adds value; no redundancy or irrelevant detail is present.

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's utter simplicity (zero parameters), rich annotations, an explicit rate-limit, operational latency, and complete usage guidance, the description covers everything an agent needs to invoke it correctly. No output schema exists, so no return-format explanation 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?

The input schema has zero parameters, which is a baseline '4' since there is no parameter semantic gap. The example call `self_test({})` confirms an empty argument object, but there is nothing richer to convey. None needed beyond this.

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 specifically what the tool does: it is a 'live capability probe' that 'verifies the service is healthy, each claimed operation is reachable, and supply network size is current.' The verb 'verifies' and the resource scope (the service itself) make the purpose unmistakable and distinguish it from siblings like verify_business or verify_company_record, which concern external records.

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 gives explicit when-to-use guidance: 'at agent startup, before high-stakes task sequences, or after receiving unexpected errors.' It also provides a clear exclusion: 'do not call more than once per minute in production.' An onboarding example query further anchors the appropriate user intent. No ambiguity remains 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 the annotations, the description discloses substantial runtime behavior: the compliance gate across jurisdictions, consent enforcement and rejection with compliance_violation receipts, channel fallback, ~800ms latency, sync_fast execution, and retrieval via get_outcome. This gives an agent a clear model of side effects and constraints.

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 structured with clear sections and front-loads the core purpose, which helps an agent quickly categorize the tool. It is somewhat longer than necessary and has a duplicate 'SMS' typo, but cost, latency, and execution details are relevant and compact.

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 messaging tool with no output schema, the description covers important contextual behavior such as compliance rejection, channel abstraction, scheduling-related consent, and the use of get_outcome. It is missing clarity on exact result/output shape and does not compensate fully for the mismatch between its examples and the actual input schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 40%, so the description must compensate, but it does not reconcile with the actual schema. Example calls use 'recipient_id', 'channel_preference', 'message', and top-level 'country_code' while the schema specifies 'recipient' with 'id_type'/'id_value', 'preferred_channel', and 'content'; the description also references a consent_record_id parameter that does not appear in the schema at all. This is a meaningful invocation-safety 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 opens with a specific verb+resource: 'Send a message on behalf of an agent's user or an SMB across SMS, email, or voice.' It also clearly differentiates this from sibling tools by naming send_transactional_confirmation as the tool for OTPs and critical transactional confirmations.

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 sections are explicit, including concrete scenarios like confirming bookings, replying to customer-initiated messages, follow-ups, reminders, and marketing with consent. It also states exclusions: OTPs, bulk/drip/cold outreach, and marketing without a valid consent record.

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 calls the tool 'Idempotent transactional messages,' but the annotations set idempotentHint to false, which is a direct contradiction. It also does not disclose the destructiveHint that is present in 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 organized with useful labeled sections and is not overly long, but it repeats the 'do not use for marketing' guidance in both WHEN TO USE and WHEN NOT TO USE. The example contributes significant bulk while being incorrect, reducing the overall structural value.

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 helpful operational context such as cost, latency, and a pointer to get_outcome for results, and it warns against marketing/conversational messages. However, it does not provide correct parameter usage details, omit important annotation-disclosed behavior, and lacks output/result shape information, which is especially problematic with a nested object and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The example query uses 'recipient_id', 'channel_preference', and confirmation_type 'booking', none of which match the actual schema fields ('recipient' object, 'preferred_channel', 'booking_confirmation'). With only 25% schema coverage, the description needed to compensate, but instead introduced invalid parameter names and values that would mislead an agent.

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 as sending idempotent transactional messages such as OTPs, booking confirmations, payment receipts, and cancellations, and separates it from marketing/conversational messaging. It stops short of explicitly naming a sibling alternative like send_message for comparison.

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 explicitly stated, including exclusions for marketing and conversational messages. However, it does not name the specific alternative tool(s) an agent should choose instead, only the category of message not to use this tool 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?

Annotations already communicate readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond them: the tool performs a live probe against a business channel, and it includes concrete cost ($0.02) and latency (~500ms) information. No contradictions.

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 and economical: a tight definition, one clarifying example, explicit usage boundaries, and cost/latency metadata. Every section earns its place, and the core behavior 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?

The description is nearly complete for a two-param read-only tool: it specifies purpose, example, when to use/not use, cost, and latency. It does not describe the result shape (Boolean vs object), but with no output schema provided this is less critical; for a real-time profile probe the essential context 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?

Schema description coverage is 0%, so the description must compensate. It assigns meaning to both parameters: smb_id as the business identifier and capability_to_verify as the requested service to confirm. The worked example ('smb_imp_abc', 'emergency_plumbing') makes the relationship concrete, though it does not enumerate accepted capability values or ID formats.

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 clear verb-resource pair ('Confirm that an SMB...') and explicitly defines the scope: real, currently operating, and capable of the requested service. It stands apart from siblings like verify_company_record and find_business by adding a 'live capability probe' and giving a concrete example query.

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 and WHEN NOT TO USE sections. It names the specific context (unverified SMB identifier, confirmed capability needed) and the exact exclusion condition for find_business (results within the last 24 hours), which directs the agent to the correct sibling.

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, the description commits to a specific non-fabrication behavior: if a company is not found, it returns an 'honest not_found' with the queried sources. It also discloses that the lookup is live, free, covers GLEIF and EDGAR, and gives latency expectations, which is valuable behavioral detail beyond what annotations 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 organized and front-loaded with a summary, followed by useful structured sections for examples, when-to-use, when-not-to-use, cost, and latency. It is longer than the minimum but every section serves a distinct purpose; only minor redundancy occurs (e.g., mentioning free in both the summary and the COST line).

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 sufficiently tells the agent what will be returned: official legal name, LEI, entity status, jurisdiction, registered address, registry authority, and sock_type or a not_found designation. Combined with the input schema, examples, and explicit constraints, an agent has everything needed to call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by giving valid example calls, showing how 'lei' can be used as a precise direct lookup alongside 'name', and explaining 'country' as an optional jurisdiction filter. This goes beyond the raw schema descriptions and helps the agent select the right combination.

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 ('verify a company registry record'), identifies the data sources (GLEIF and SEC EDGAR), and names what is returned. It does not explicitly distinguish itself from the sibling tool verify_business, so it does not earn a 5, but the purpose is 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 provides strong context with 'WHEN TO USE' and 'WHEN NOT TO USE', including concrete use cases like contract signing and due-diligence checks. It excludes private companies not in GLEIF/SEC and warns it is not a full KYC screen, but it does not name alternative sibling tools, so it falls short of explicit alternatives guidance.

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