Agent Broker

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds rich behavioral context: async execution by default, polling via get_outcome, compliance recording-consent routing, B2B-framing restrictions, cost per call, and latency. This goes well beyond the structured fields and gives the agent a clear model of side effects and operational behavior.

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

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

The description is well-structured with clear sections for purpose, usage, cost, latency, and execution mode. The most important differentiator is front-loaded, examples are short and illustrative, and every section earns its place despite the length.

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

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

For a tool with 8 parameters, no output schema, and notable compliance and cost implications, the description is complete: it explains the call flow, how results are obtained, when to avoid the tool, and the operational constraints. An agent has enough information to decide whether and how to invoke 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 description coverage is 88%, so the parameter burden is mostly carried by the schema. The tool description adds a little context around plain-language objectives and that results are retrieved as transcript plus extracted fields, but it does not materially explain individual parameters beyond what the schema already provides. Baseline 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 opens with a specific action and resource: placing a conversational voice-AI call to a business on a consumer's behalf and returning a structured answer. It further distinguishes itself by emphasizing the unique capability to reach long-tail SMBs with no API or booking page, clearly separating it from sibling tools like schedule_appointment and import_booking_url.

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 explicitly define the target scenario, give concrete examples, and name exact alternative tools (import_booking_url + schedule_appointment) to avoid. It also excludes consumer calls and marketing use cases, leaving no ambiguity about appropriate invocation.

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

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

Beyond the skeletal annotations, the description discloses storage semantics (AgentBroker lead store, not CRM), dedup/validation behavior, cost ($0.05), latency (~600ms), and async-style result retrieval via get_outcome. No contradiction with annotations; the write behavior matches readOnlyHint=false.

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 purposeful sections: core purpose, example, when to use/not use, then cost/latency/execution. Each section earns its place, though the example JSON adds length; overall it is appropriately sized and 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 compensates by referencing get_outcome for results and giving cost, latency, and execution mode. It covers the critical distinction from the SMB's own CRM and the primary routing rules; the only minor gap is a precise description of the response receipt, which is delegated to get_outcome.

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 call maps a natural-language request to concrete values for smb_id, prospect, and source, and the dedup note clarifies the role of smb_id/phone/email. Schema descriptions cover source and idempotency_key, so the description adds value without needing to repeat them; some prospect subfields remain undocumented but are self-explanatory.

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 uses specific verb 'intake'/'stores' with resource 'prospect into SMB's funnel,' and adds key differentiators: validation, deduplication on (smb_id, phone/email), and explicit note that it writes to AgentBroker's own lead store, not the business's CRM. This clearly distinguishes it from siblings 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 state the triggering condition (prospect expressed interest) and exclusions (confirmed bookings -> schedule_appointment; bulk imports). Also notes follow-up retrieval via get_outcome, which guides the call flow.

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

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

The description goes well beyond the annotations: it discloses that the tool does NOT fetch the URL or spend money, classifies URL shape only, and returns platform, smb_id, channels, and inferred country. It also includes free cost and sub-100ms latency, which the annotations do not convey. No contradiction with readOnlyHint, idempotentHint, or destructiveHint.

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?

Although lengthy, every section earns its place: core behavior is front-loaded, followed by concrete examples, usage guardrails, and cost/latency. The structured formatting makes it easy for an agent to scan and extract decision-relevant information 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 tool with no output schema, the description is remarkably complete. It covers what the tool returns, what it does not do, when to use it, when not to use it, how to interpret the result, and the cost/latency profile. An agent has everything needed to invoke it correctly and decide next steps.

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 a clear description for the single url parameter, including an example format, so baseline is 3. The description adds value with concrete user-query-to-parameter mappings, reinforcing exactly what URLs look like and how the agent should pass them.

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: 'pre-flight check for a booking URL' that classifies platform and predicts whether import_booking_url will accept it. It also explicitly distinguishes itself from import_booking_url and verify_business, making its unique role unmistakable.

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' and 'WHEN NOT TO USE' section. It tells the agent to call this tool as a free guard before paid actions, and explicitly states it should not replace import_booking_url, verify_business, or be used to confirm a page is live.

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 no state changes, free execution, sub-100ms latency, and the generation of a signed, hash-bound compliance_receipt verifiable offline. It also clarifies that the gate re-runs at send time and that two-party voice recording consent is out of scope. No contradiction with annotations.

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

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

The description is long but well-structured and front-loaded with the core purpose. Example queries, WHEN TO USE, and WHEN NOT TO USE all earn their place. Minor redundancy exists because 'free' and 'fast' appear in the description, Cost, and Latency sections, but overall density is high.

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 explains what the tool returns: whether the send is permitted, the exact rule if blocked, remediation, and a signed receipt. It also covers cost, latency, trigger conditions, exclusions, and a verification URL. Nothing essential for correct tool selection and invocation 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 the baseline is 3. The description adds meaningful semantics: marketing triggers consent checks, channel and country_code can be auto-inferred, and content must be the real message body. The example queries map natural-language requests to concrete parameter values, which helps an agent construct valid 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 states a specific verb and resource: it is a 'pre-flight' compliance check that runs the same TCPA/GDPR/CASL/CAN-SPAM/10DLC gate as send_message and call_business, but in preview mode. It clearly differentiates itself from sibling tools by emphasizing that no message is sent and no state changes.

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 it immediately before send_message or call_business for regulated sends, gives concrete triggers such as marketing messages, US SMS, GDPR, and CASL, and warns against treating legal=true as a permanent license or substituting it for delivery.

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 readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: the tool is free, requires no API key, accepts any valid X-Agent-Identity token, and returns tier='anonymous' for keyless callers with anonymous limits. It also discloses cost and latency, giving the agent a fuller operational picture.

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?

Although longer than average, every section earns its place: clear function summary, motivating example queries, explicit usage guidance, and cost/latency notes. The information is front-loaded and organized, with 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?

With no output schema, the description compensates by listing the exact return fields and reset behavior. It also covers authentication edge cases, cost, latency, and usage frequency, making it complete for an agent to decide when and how to invoke the 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?

The input schema has zero parameters, so there is no semantic ambiguity to resolve. The description reinforces the empty call shape with check_quota({}) examples, matching the baseline of 4 for parameterless tools.

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: 'Returns the caller's current quota state', and enumerates the exact fields returned (operations used, remaining, daily limit, tier, reset time). This clearly differentiates it from siblings like check_compliance and get_status.

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, including when to call proactively and after a rate_limited error. It also tells the agent not to call on every invocation because quota is already injected into write-tool responses, which serves as an alternative source of the information.

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 signal destructiveHint and non-read-only behavior. The description adds useful behavioral context: async execution by default, the need to use get_outcome for the result, cost, and latency. It could further explain the irreversible or externally visible side effects of escalation, but the hand-off framing plus annotations cover the essential 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?

The description is longer than average, but every section—example, when to use, when not to use, cost, latency, execution mode—earns its place and is front-loaded with the core purpose. 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 complex async tool with no output schema, the description supplies the critical operational details: async execution, result retrieval via get_outcome, cost, latency, when to escalate, and when not to. An agent has enough information to invoke it correctly.

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

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

Schema description coverage is low, but the description compensates by naming the context fields, showing a full example call, and indicating how reason, context, priority, and smb_id are used. It does not define every enum value or nested subfield, but the schema enumerations and example fill most gaps; idempotency_key is well documented in the schema itself.

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: hand off an in-flight task to a human operator with a context bundle. Includes the exact bundle contents and a concrete example query, which makes the tool's purpose unmistakable and distinguishes it from sibling tools 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?

Explicitly provides WHEN TO USE and WHEN NOT TO USE guidance, including the key exclusion 'Do not use as a first resort.' This directly helps the agent decide between this tool and automated 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?

Beyond the readOnly/idempotent annotations, the description discloses critical behavior: the supply network is mostly sample data, [DEMO] entries must be checked via is_demo, and availability_window is accepted but NOT APPLIED, with the response indicating availability_window_applied false. It also notes cost and latency.

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, front-loaded with purpose and critical warnings, followed by examples, usage guidance, and constraints. Every section earns its place, especially the sample-data warning and the availability_window caveat.

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 nested objects, no output schema, and several behavioral traps, the description is nearly complete: it covers inputs, result caveats, when to use, when not to use, follow-up routing, and key output fields like is_demo and availability_window_applied. The only minor gap is a full response field list, which is not essential 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 coverage is only 50%, so the description compensates with concrete query-to-parameter examples for vertical, location, and capability, and it explicitly warns about the non-applied availability_window. Price_band and max_results/radius are less detailed, though their schema names and defaults make them reasonably self-explanatory.

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 clear action—'return ranked candidate businesses from our supply network'—with explicit search criteria and a defined result type. It also distinguishes itself from related siblings by saying when it should not be used, e.g., when a verified SMB identifier already exists.

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 explicitly name alternatives: call this before schedule_appointment or send_message when no specific SMB is known, and do not use it as a general directory or when a verified SMB is already in hand. It also restricts valid verticals, which prevents misuse.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds valuable behavioral context beyond that: it reveals the polling use-case, the exact thread-matching guarantee, the 10-second rate constraint, and cost/latency characteristics. This goes well beyond the structured 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 a front-loaded purpose, concrete examples, explicit usage rules, and concise cost/latency notes. Every section earns its place and the length is appropriate for the tool's complexity.

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 tells the agent what the tool returns (state, messages, reply count), when to call it, how to identify the correct conversation, and operational constraints. An agent has enough information to select and invoke 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 description coverage is 100%, so the schema already documents all three parameters. The description adds realistic example mappings and clarifies that reference requires business_number, but most of that is also present in the schema. It is acceptable but does not meaningfully expand on the structured parameter definitions.

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 ('Read'), a specific resource ('a two-way conversation thread you started'), and the exact content returned (state, every message, reply count). It clearly distinguishes this from generic status/outcome tools among the siblings by emphasizing the two-way thread and the business's replies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit WHEN TO USE guidance: after send_message returns a conversation_id, poll this tool to read the business's reply. Also gives a clear WHEN NOT TO USE restriction (do not poll more often than every 10 seconds), and adds a safety guarantee that replies are matched to the exact thread. This is strong contextual routing for an agent.

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 non-destructive behavior, so the description's job is lighter. It adds useful behavioral context beyond annotations: the operation is free, requires no key, has ~50ms latency, and returns cost and reason codes. 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 compact, front-loaded with the core purpose, and uses labeled sections for usage, cost, and latency. Every line adds practical value with no fluff or repetition of schema/annotation data.

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

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

For a one-parameter tool with no output schema, the description covers the key operational context: when to call, when not to call, what the result contains, and operational constraints like cost and latency. It stops just short of stating error/not-found behavior, but this is a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate. It implies operation_id refers to a completed operation's ID and ties it to get_status, but it never explicitly explains how to obtain or format operation_id. The single parameter is self-explanatory by name, but the low coverage keeps this at a moderate score.

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 action ('Retrieve'), the specific resource ('final OutcomeReceipt'), and the condition ('for a completed operation'). It distinguishes itself from get_status by defining the exact state transition point, so an agent can confidently select it.

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 provide direct routing: use after get_status returns a terminal state, and avoid for pending/executing operations. It even names the alternative (get_status), making the decision boundary 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it mentions latency (~50ms), cost (free), and the nature of the operation (polling for in-flight async ops). It does not contradict annotations. While it doesn't detail response structure, the description goes beyond annotations by adding usage constraints and performance characteristics.

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 concise and logically structured with headers. The primary purpose is stated first, followed by usage guidelines, cost, and latency. Every sentence provides actionable information without redundancy or 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?

Given the tool's simplicity (single parameter, no nested objects, no output schema), the description provides sufficient context for an agent to use it correctly. It covers when to use, constraints, and operational characteristics. The only minor gap is the lack of explicit mention of what response fields to expect, but since it's a status query and the description names the resource, agents can reasonably infer it returns status information. Overall, it's highly complete for a polling 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?

The input schema has no description for operation_id (0% coverage), so the description must compensate. It explicitly states that operation_id identifies the async operation, which adds meaning beyond the schema's type-only definition. Since there is only one parameter and its purpose is clear, the description adequately compensates for the low 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 clearly states the tool's purpose: 'Query the current state of any in-flight async operation by operation_id.' It uses a specific verb (query) and resource (state of async operation) with a clear parameter. This distinguishes it from sibling tools like get_outcome which likely deals with different data, and it is not a tautology.

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?

Explicitly provides 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It advises polling for pending operations and warns against excessive polling ('Do not poll more frequently than once per 10 seconds'), suggesting webhook delivery for real-time updates. This gives clear conditions and alternatives, which is exemplary 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?

Annotations only provide generic hints (readOnlyHint=false, idempotentHint=false), so the description carries the behavioral burden. It discloses that opt-outs are recorded durably, no other action is auto-executed, execution is async by default, results must be retrieved via get_outcome, and it adds cost and latency details. This is strong context beyond what annotations and schema 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 clear headings, front-loads the core purpose, and uses a runnable example that earns its place. Cost, latency, and execution mode each get a single concise line, and no content feels redundant with the schema.

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 no output schema and seven parameters, the description covers required call shape, intents, use cases, exclusions, async result retrieval, and operational characteristics. The main gap is the lack of detail about the exact shape or possible values of suggested_action beyond the intent list, but the definition is sufficient for safe 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 29%, but the description compensates with a concrete example call that maps a natural-language request to the three required parameters: smb_id, inbound_channel, and raw_message. The WHEN TO USE section also clarifies channel semantics. Optional parameters like sender and received_at_iso are left to self-evident names and schema structure, so it is helpful but not exhaustive.

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 specific verb-resource pair ('Classify an inbound message on behalf of an SMB') and defines the output ('recommended next action'), while explicitly listing the intents it handles. It also distinguishes itself from send-style tools by noting that nothing is auto-routed or auto-executed except durable opt-out recording.

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 concrete inbound contexts (contact forms, SMS replies, voicemails, emails) and exclusions (outbound communications, compliance-flagged recipient lists without verified opt-in records). This gives an agent direct decision criteria without needing to inspect sibling 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?

Beyond the idempotentHint annotation, the description discloses cost implications (free but requires email-verified key), approximate latency, auto-detection of platform from host, and automatic extraction of vertical/business name when omitted. These are behavioral details not present in annotations or schema.

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: opening summary, realistic examples, explicit usage criteria, cost, and latency. It is front-loaded with the core transformation and output, with supporting details structured under clear headings.

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 no output schema, the description conveys the key output (smb_id), the idempotent receipt behavior, and downstream usage, which covers the critical integration handoff. It stops short of specifying the exact response field structure, but the examples and 'returns the same smb_id' language are sufficient for an agent to proceed.

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 all parameters thoroughly, including vertical inference, country_code compliance use, business_name extraction fallback, and idempotency_key replay semantics. The description reinforces this with usage examples but does not add new parameter meaning beyond the schema.

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

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

The description names the exact operation ('Turn ANY public booking URL ... into a callable smb_id'), enumerates supported platforms, and frames the tool as the import step before schedule_appointment, send_message, or capture_lead. It also explicitly contrasts with find_business in the WHEN NOT TO USE section, removing ambiguity among 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 contains dedicated WHEN TO USE and WHEN NOT TO USE sections, gives concrete user-query patterns that match, and names the alternative (find_business) for the non-URL case. This is explicit routing guidance, not just implied context.

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, so the bar for extra value is met by the description's additions: data source (USASpending.gov), coverage years (2020-2026), zero cost/no key, latency, and output fields. It does not contradict the annotations. Minor gap: no statement about exact-match vs fuzzy matching or empty-result behavior.

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

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

The description is longer than average but well structured with clear sections (purpose, examples, when to use, when not, cost, latency). Main purpose is front-loaded. Minor redundancy exists between 'Zero upstream cost, no key required' and the COST section.

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 low parameter count and lack of an output schema, the description compensates well by specifying the returned award fields, data source, date range, sort order, and constraints. It is complete enough for an agent to invoke correctly, though details about no-result responses or name-matching behavior are absent.

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 both parameters are already clearly documented in the input schema. The description reinforces company_name via examples and max_results via the sort order, but does not add significant new meaning beyond the schema. Baseline 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 names a specific verb and resource ('Search US federal contract awards by company name') and lists the exact returned fields (award ID, recipient, amount, agency, NAICS, period). It clearly distinguishes itself from related tools like verify_company_record and screen_sanctions by stating what it covers and what it does not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The tool has an explicit WHEN TO USE section with concrete scenarios and a WHEN NOT TO USE section that names alternative tools (verify_company_record, screen_sanctions) and exclusions (non-US, state/local, financial-risk screening). This is exactly the guidance an agent needs to select between siblings.

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 readOnly/idempotent annotations, it discloses the non-classification behavior, the 'partial' reason_code for controlled items, a policy never to fabricate rates/clear/restricted status, and cost/latency. 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?

Highly structured with front-loaded limitation, examples, and usage rules, but it is long and contains some redundancy (e.g., middleman unification repeated). Still every major section contributes.

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?

Covers return categories (a)-(e), error behavior for party-list size, country coverage, and commercial conditions; with no output schema this is enough to know what will happen. It could specify exact JSON response shape, but isn't needed 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 coverage is 100%, so baseline is 3, but the description adds behavioral detail (product is echoed and never classified; parties must be split if >20; destination checked against OFAC lists) and provides four concrete example invocations that map user wording to parameter values.

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 ('cross-border trade screening of DESTINATION and PARTIES') with a clear boundary that it does not classify product, and it distinguishes its consolidated middleman behavior from export-control/product classification. The examples reinforce the tool's role.

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?

Has labeled WHEN TO USE and WHEN NOT TO USE sections with explicit pre-flight use, coverage list, and exclusions (licensed review, authoritative tariff rates, domestic shipments). This is the clearest possible routing guidance for an agent.

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 minimal annotations, the description reveals key behaviors: returns a usable key immediately, returns an honest not_configured failure if no mint secret is activated, and advises calling it once and branching on the result. It also discloses cost, latency, and the free-tier operation limit, giving the agent a full picture of the tool's behavior.

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

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

The description is longer than average but well-organized into labeled sections (WHEN TO USE, WHEN NOT TO USE, COST, LATENCY) with the core purpose front-loaded. The example query is somewhat detailed but earns its place by showing exact parameter usage. Minor redundancy in phrases like 'no email inbox'/'without a human email address' prevents a perfect score.

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 adequately covers the primary return behavior: a usable key or a not_configured failure. It also mentions the free-tier limit. However, it does not mention other possible failure modes such as invalid signature or expired timestamp, which would be useful for an agent but are partially inferable from the schema. Otherwise it is fairly 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?

The input schema already covers all four parameters with 100% coverage, so the baseline is 3. The description adds extra value by giving a concrete example matching the parameter set, clarifying that the caller must know MACHINE_MINT_SECRET, and reinforcing the raw-concatenation HMAC format. This lifts it above 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 description opens with a specific verb+resource: 'Agent self-serve API key issuance' and immediately explains that an agent can 'obtain a free-tier API key' via HMAC proof. It clearly distinguishes itself from sibling tools by focusing on self-provisioning without an email inbox, making its unique role obvious.

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 explicitly state when to use this tool (agent with no email, knows MACHINE_MINT_SECRET) and when to avoid it (human operator can complete email flow at /keys/request, paid plans). It also notes the free-tier limit, leaving no ambiguity about applicability.

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 readOnlyHint/idempotentHint annotations, the description adds meaningful behavioral detail: it returns exact price when fixed, a min/max range when cost depends on channel or outcome, does not promise an accuracy percentage, and warns the agent to check cost_range. It also discloses operational characteristics: 'COST: free - no key required' and 'LATENCY: ~100ms.' No contradiction with annotations exists.

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

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

The description is well-structured and front-loaded: the first sentence states the core purpose, followed by pricing behavior, an accuracy caveat, and practical usage guidance. The examples are compact but illustrative, and every section (WHEN TO USE, WHEN NOT TO USE, COST, LATENCY) adds operational value without 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?

With no output schema, the description carries the burden of explaining return values, and it does so clearly: cost estimate with exact/range behavior, latency estimate, success-probability estimate, and the cost_range field to check. It also covers when to call, when not to, cost, latency, and parameter examples. For a simple two-parameter preview tool, nothing essential 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 schema description covers only params ('The same request body you would pass to the operation'), leaving operation undocumented. The tool description compensates with concrete examples mapping operation values like 'send_message' and 'schedule_appointment' to realistic params, clarifying that operation names the target call and params mirror its request body. Still, the operation parameter semantics remain partially implicit.

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 specific verb-resource pair: 'Return an expected cost estimate, latency estimate, and success-probability estimate for a proposed call before execution.' It clearly identifies the tool as a pre-execution preview, which separates it from execution tools like send_message or schedule_appointment. However, it does not explicitly differentiate from closely related sibling tools such as check_quota, so it stops just short of full sibling distinction.

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: 'Use before any operation when the agent is operating under a budget constraint and needs to decide whether to proceed' and 'Do not use in a hot loop — cache the result for at least 60 seconds.' This provides clear context and exclusion criteria, including a caching strategy instead of repeated calls.

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 destructiveHint=true, but the description adds substantial behavioral context: async_by_default execution with 'use get_outcome to retrieve result', approximate cost and latency, and the fallback routing through the SMB's native booking system, voice AI, or web form. 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 purpose, followed by compact example queries, then labeled WHEN TO USE/WHEN NOT TO USE, cost, latency, and execution sections. Every section earns its place and the formatting makes it easy for an agent to scan.

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 an 8-parameter tool with nested objects, multiple actions, async execution, and no output schema, this description covers prerequisites, exclusions, routing, and result retrieval via get_outcome. However, it does not specify what a successful call returns or how actions must be paired with action-critical parameters, leaving a modest but real completeness gap.

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

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

Schema description coverage is only 25%, so the description needed to compensate, but it only demonstrates smb_id, action, and service in examples. Critically, the reschedule and cancel examples omit existing_appointment_id even though the schema marks it 'Required for reschedule/cancel', and requested_time/customer are never explained. An agent cannot reliably construct complete calls from this description.

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 statement: 'Availability lookup, hold, confirm, reschedule, or cancel appointments with an SMB.' It maps cleanly to the action enum and clearly differentiates this tool from sibling tools like find_business and get_outcome. The only minor wrinkle is that 'hold' and 'confirm' appear in prose but not in the enum, yet the purpose is still 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?

WHEN TO USE and WHEN NOT TO USE are explicit: use for booking/rescheduling/canceling a specific appointment with a specific SMB, avoid bulk scheduling, and do not use without a verified smb_id — with direct pointers to find_business and verify_business. This gives the agent clear decision criteria and even names 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?

Goes far beyond annotations by disclosing critical behaviors: the UN list is deliberately excluded, lists_screened must be checked, reason_code is 'partial_screening' when sources fail, screening_status should be branched on rather than matched, and a verifiable compliance_receipt is attached. It also warns that country never removes results and that a negative result is not clearance. No contradiction with readOnly/idempotent 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 long but every section earns its place: purpose, source details, response interpretation warnings, compliance receipt, examples, use cases, cost, and latency. It is well-structured and front-loaded with the essential purpose before detailed caveats.

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 thoroughly explains return fields (screening_status, matched, matches, lists_screened, sources_unavailable, reason_code) and edge cases. It also includes cost/latency context, making it fully 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema. For the country parameter it explains that the value 'ANNOTATES AND RANKS results; it never removes any' and describes country_match semantics. Example user queries map arguments to calls, enriching all parameters.

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?

Opens with a specific verb and resource: 'Free screening of a name or entity against official sanctions lists.' It names the exact lists screened (OFAC, EU, UK), explicitly excludes the UN list, and distinguishes itself from broader compliance tools by stating it covers sanctions only, not KYC/AML.

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 dedicated WHEN TO USE and WHEN NOT TO USE sections with concrete scenarios (onboarding, payment, vendor qualification) and exclusions (not for PEP/adverse media/credit risk, not for bulk screening). It clearly tells an agent when to invoke this tool and when to avoid 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?

Annotations already mark it read-only and idempotent, but the description adds valuable behavior beyond that: exactly 6 internal checks, reports how many passed, does not probe each tool individually, requires no key, has ~200ms latency, and carries a rate limit. These operational details help the agent understand 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 well-structured and front-loaded: core behavior first, then an example, then usage guidance, cost, and latency. Every section contributes practical information without redundant filler or excessive length.

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

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

For a zero-parameter health probe with rich annotations, the description covers everything needed to invoke it correctly: purpose, result shape, timing, rate limit, authentication requirement, and performance expectation. The absence of an output schema is acceptable because the description states what the tool reports.

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

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

The tool takes zero parameters, and the schema description coverage is 100%, so there is no parameter ambiguity. The example call self_test({}) reinforces that no arguments are needed, which is the appropriate baseline for a parameterless tool.

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

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

States a specific verb and resource: 'runs 6 internal checks and reports how many passed'. It also explicitly clarifies the tool's scope by saying it 'does NOT probe each tool individually', which distinguishes it from sibling tools that verify or probe individual business entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit WHEN TO USE and WHEN NOT TO USE sections: at startup, before high-stakes task sequences, after unexpected errors, and no more than once per minute in production. The example user query also shows a concrete matching scenario, leaving little ambiguity for the agent.

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 signal a mutating, non-idempotent, open-world operation, but the description goes far beyond: it discloses the non-bypassable compliance gate, consent enforcement, channel fallback, rate limiting, scheduling refusal, idempotency replay behavior, cost, latency, and execution model. It even names the failure receipt type (compliance_violation).

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 headers, examples, and a front-loaded core statement. There is some repetition of the marketing-consent rule, but it reinforces a critical constraint rather than 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?

For a complex 8-parameter mutation tool with no output schema, the description covers when to use, when not to use, compliance behavior, cost, latency, scheduling limits, and result retrieval via get_outcome. It does not fully specify the success response shape beyond mentioning receipts, so an agent still has to infer part of the return contract.

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

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

With only 63% schema description coverage, the description compensates well: it explains message_type consent coupling, preferred_channel as an abstraction/fallback, send_at_iso refusal behavior, and on_behalf_of rationale. The two examples map recipient and content to realistic values, though parameters like template_id, template_vars, and business_id still rely on schema 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?

The opening sentence names the action (send), the resource (message), the beneficiaries (agent's user or SMB), and the channels (WhatsApp, SMS, email, voice). It clearly distinguishes the tool from send_transactional_confirmation by explicitly excluding 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?

The description provides an explicit WHEN TO USE list with five concrete scenarios and a WHEN NOT TO USE section that names the alternative tool and prohibitions. This gives an agent unambiguous routing guidance, including consent requirements and bulk-outreach restrictions.

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 explicitly claims 'Idempotent transactional messages' and details idempotency key behavior, but the annotation `idempotentHint: false` directly contradicts this. The description also mentions fallback and honest failure, but the idempotency contradiction is critical and violates the annotation contract.

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 a core paragraph, an example, and explicit usage sections. It is front-loaded with purpose and behavior, but includes extra metadata (cost, latency, execution) that, while useful, could be placed more concisely. Overall, it earns its length.

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

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

The description covers fallback behavior, execution mode, cost, latency, and how to retrieve results via get_outcome. Despite lacking an output schema, it explains the execution flow completely. The idempotency contradiction and lack of explicit return value rationale slightly reduce completeness, but the tool is well-contextualized.

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 must compensate. It provides an example payload structure and explains the idempotency_key semantics (replay behavior, 24-hour window, no re-execution/re-charge), which adds value beyond the schema. However, it doesn't detail all parameters, but the schema already covers recipient and enumeration values adequately.

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 'Idempotent transactional messages: OTPs, booking confirmations, payment receipts, cancellation notices,' which names a specific resource type and scope. It differentiates from siblings like send_message by explicitly excluding marketing and conversational use. The example query further anchors the purpose.

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 clearly state the intended scenarios (OTPs, confirmations, receipts) and explicitly exclude marketing and conversational messages. This provides direct guidance on when to select this tool over alternatives like send_message.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds crucial behavioral context beyond those: it does not contact the business, it is a directory lookup, it costs nothing, and typical latency is ~500ms. This is exactly the kind of non-obvious behavior an agent needs to know before invoking.

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 into clear labeled sections and front-loads the core behavior. The example query, usage guidance, cost, and latency each earn their place and no section is redundant. The formatting 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?

Despite having no output schema, the description covers what the tool returns, when to use it, when not to use it, cost, latency, and the critical 'does not contact the business' caveat. An agent has enough context to select and correctly invoke the tool with the right parameters.

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 carries the burden. It adds meaning to both parameters: smb_id is an 'SMB identifier' and capability_to_verify is demonstrated in the example query ('emergency_plumbing') and in WHEN TO USE ('confirmed capability'). It does not fully specify allowed capability values or behavior when omitted, but the example and context provide strong compensation.

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 ('Look up') and resource ('a business in our supply network') and lists the exact data returned: contact channels, capabilities, and last verification time. It explicitly distinguishes itself as a DIRECTORY LOOKUP that does not contact the business, which separates it from sibling tools like call_business and 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 description provides explicit WHEN TO USE and WHEN NOT TO USE sections, plus a concrete user query example. It names find_business as the sibling alternative and gives a clear condition ('returned from find_business within the last 24 hours') under which this tool should not be used.

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 and idempotentHint=true, so the description's 'Never fabricates' and 'honest not_found' statement add behavioral guarantees beyond the schema. It also discloses cost (free within quota, then $0.02/call) and latency (~800ms), which are not implied by annotations. It does not describe any error cases beyond not_found, but that's covered. Overall, it adds meaningful context 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 description is longer than typical but is well-structured with bullet-like sections (WHEN TO USE, WHEN NOT TO USE, COST, LATENCY) and example queries. It front-loads the core purpose and then adds usage context. Slight redundancy exists ('Free' appears twice), but it's not verbose enough to detract seriously. Every section adds 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?

With 3 parameters, no output schema, and no nested objects, the description must convey the return format and behavior. It does so by listing the returned fields, stating the not_found behavior with the queried sources, and covering cost and latency. It also anticipates edge cases (private companies, fraud detection) via the exclusions. Nothing an agent needs to call it 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 coverage is 100%, but the description enhances each parameter: it explains 'name' works with a legal name, 'lei' is a 20-character identifier for a direct precise lookup, and 'country' narrows GLEIF results to a jurisdiction. The examples show how to combine name+country and name+LEI, giving agents concrete usage patterns that the schema alone lacks.

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: 'Free, live lookup of a company official registry record,' and enumerates exactly what it returns (legal name, LEI, status, jurisdiction, address, authority). It also differentiates itself from siblings by naming the data sources (GLEIF and SEC EDGAR) and clarifying it is a first-pass existence check, not a full KYC screen. Example queries further cement its purpose.

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. The WHEN TO USE states clear trigger conditions (contract signing, vendor qualification, counterparty validation, due diligence) and the accepted input forms (name+optional country, or LEI). The WHEN NOT TO USE section explicitly excludes private companies not in GLEIF/SEC and clarifies it is not a fraud-detection tool, steering agents away from misuse, even though it doesn't name a specific sibling alternative.

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