Agent Broker

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

The description discloses key behavioral traits: it's not wired and fails with voice_not_provisioned before dialling, is async via get_outcome, and has per-call pricing. However, it directly contradicts the annotation destructiveHint=true by stating calls fail before dialling and are uncharged, implying no side effects. This is a clear contradiction, so per rubric the score is 1.

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

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

The description is compact yet dense, covering purpose, failure mode, usage, compliance, pricing, and async behavior in a few sentences. It front-loads the main action and then provides caveats. Each sentence adds value, though it could be slightly tightened.

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 complexity (8 params, async, failure mode), the description covers essential operational aspects: it's not wired, async, pricing, compliance, and how to use it. It doesn't describe the success output, but that's handled by get_outcome. It could mention the requirement for either smb_id or business_phone, though that's in the 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 coverage is 88%, so most parameters are already described. The description adds minimal parameter-specific info beyond saying 'Give a plain-language objective,' which maps to the objective field. It doesn't elaborate on smb_id vs business_phone or other parameters. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's specific action: placing a conversational voice-AI phone call to a business on a consumer's behalf. It also mentions it navigates the call and extracts answers, and it's distinguished from siblings like send_message or check_booking_link. The 'NOT WIRED' caveat adds context without obscuring 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 description gives clear context for when to use it: it's business-directed (B2B), less restricted than consumer calls, and requires a plain-language objective. It also warns that the tool is not wired and will fail, which is crucial for an agent. However, it doesn't explicitly name alternatives or state when NOT to use it, so it's not a 5.

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

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

Annotations only indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable context: it is a mutation that stores a prospect, performs validation and deduplication, is async, and incurs a cost. It also clarifies the storage domain (AgentBroker's store) which prevents misuse. 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 a single, dense sentence that front-loads the core purpose, includes critical distinctions (not CRM), and appends cost and async behavior. Every element earns its place with no redundancy.

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

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

The description covers the main purpose, storage location, deduplication logic, cost, and async flow. The nested prospect object is detailed in the schema, and the idempotency behavior is described in the parameter schema. While it does not explain the return format or all edge cases, it is sufficient for an agent 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 50%, so the description must compensate. It adds meaning to smb_id and prospect's phone/email by identifying them as deduplication keys, and it mentions the idempotency_key parameter implicitly through the 'async→get_outcome' note (though not explicitly). However, it does not explain other parameters like source, notes, or consent_record_id, leaving some gaps.

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 function: structured intake of a prospect with validation and deduplication on (smb_id, phone or email). It also explicitly clarifies the storage location (AgentBroker's lead store, not the business's CRM), distinguishing it from potential alternatives. This is specific and 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 implies when to use this tool (when capturing a prospect) and notes the async flow with get_outcome, but it does not explicitly name alternative tools or state conditions for not using it. The clarification that it does not write to the business's own CRM serves as an implicit exclusion, but there is no explicit 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?

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it performs no network fetch, incurs no cost, requires no key, and returns a specific set of derived values including the exact smb_id. This tells the agent exactly what side effects to expect (none) and what output to anticipate.

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 dense but every sentence adds value: what it does, what it avoids, what it returns, and when to use it. Key behavioral constraints are front-loaded, and the '[free, no key]' tag is a compact useful addition.

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 a single parameter, no output schema, and rich annotations, the description is complete. It names the return fields (platform, smb_id, channels, country), clarifies cost and safety, and situates the tool within the surrounding workflow. An agent has enough to invoke it correctly.

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

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

The input schema already documents the single url parameter with 100% coverage, including an example. The description does not materially add parameter-level semantics beyond classifying it as a booking URL, so the baseline score 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 specific verb ('pre-flight check', 'classifies') tied to a concrete resource (booking URL) and names the downstream dependent tool (import_booking_url). It clearly differentiates itself from sibling tools like schedule_appointment by framing itself as a check that happens before any paid action.

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 instructs when to use it: 'BEFORE calling import_booking_url + schedule_appointment' and why: to 'de-risk a paid booking'. It also states what it does NOT do ('WITHOUT fetching the page or spending money'), giving the agent clear usage boundaries.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds key behavioral facts: nothing is sent, nothing changes, and output includes whether a send is permitted plus the exact rule and fix. 'Free, no key' and 'before you pay' are extra operational context not 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?

Three sentences with front-loaded value—'Free, instant pre-flight'—and every sentence earns its place: what checks run, what it returns, and the analogy to check_booking_link. No filler.

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

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

For a 6-parameter tool with no output schema, the description covers what the tool does, what it returns, side effects, cost model, and the exact regulatory scope. The input schema covers parameters, so nothing needed to invoke 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 description coverage is 100%, so the schema already documents all six parameters. The description does not add meaning beyond the schema—it only says the tool checks content/recipient, which the schema already states.

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

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

The description names a specific verb/resource ('pre-flight for the compliance gate') and distinguishes the tool by stating it runs the same TCPA/GDPR/CASL/CAN-SPAM/10DLC checks as send_message and call_business in preview mode. This makes the tool's role clear and distinguishes it from sibling tools.

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

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

It says to use it before paying for a send, in preview mode, and compares it to check_booking_link for de-risking a booking. It does not spell out exclusions or explicit 'when not to use', but the preview-mode language effectively rules out using it when an actual send is intended.

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 (readOnly, idempotent, non-destructive), the description discloses that the operation is free, the authentication requirements, the anonymous fallback behavior, and the full set of returned quota fields. This significantly exceeds 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?

Two dense sentences plus a short tag convey the purpose, return fields, auth behavior, and anonymous tier case. No filler or repetition; information is front-loaded and every sentence 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?

For a zero-parameter read-only utility with no output schema, the description covers everything an agent needs: what data is returned, the auth model, the anonymous behavior, and the safety profile. Nothing critical 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 tool has zero parameters, so there is nothing to document beyond the schema. The baseline of 4 applies; the description appropriately focuses on behavior and return data instead of parameter details.

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

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

The description uses a specific verb ('Returns') and a precise resource ('caller's current quota state'), enumerating the exact data fields returned. It is unambiguous and clearly distinct from any sibling tool, none of which appear to deal with quota state.

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

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

The description provides clear usage context: it works with any valid X-Agent-Identity token and explains how keyless callers are treated. It doesn't explicitly name alternatives or state when not to use it, but no sibling tool offers this function, so the guidance is sufficient.

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

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

Annotations already provide destructiveHint=trueasi, so the description does not need to restate irreversibility. The description adds useful behavioral context beyond annotations: the cost ($0.2/per_call), the async pattern (async→get_outcome), and the exact contents of the context bundle (transcript, prior actions, identifiers, recommended next step). This is strong added transparency.

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 a single efficient sentence that front-loads purpose and then packs cost and async behavior into compact brackets. There is no fluff, and every part earns its place.

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

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

For a tool with nested context, five parameters, and no output schema, the description is adequate but incomplete. It mentions async→get_outcome but does not explicitly say what the call returns or how the escalation outcome will be surfaced. The reason enum and idempotency_key description in the schema fill some gaps, but the description alone does not fully cover the call's end-to-end behavior.

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

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

Schema description coverage is only 20%, so the description partially compensates by naming the context-bundle fields: transcript, prior actions, identifiers, and recommended next step. It does not explain required parameters like smb_id, reason, or priority, though their names and enums are reasonably self-explanatory. Overall it adds some meaning but does not fully cover 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 uses a specific verb ('Hand off') and resource ('in-flight task to a human operator'), and explains that a context bundle is included. This distinguishes it clearly from sibling tools like send_message or get_outcome, and it is not a tautology of the name.

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 implies this is for in-flight tasks and points to get_outcome for follow-up. However, it does not explicitly state when to use this vs. alternatives like handle_inbound or send_message, nor does it state when not to escalate. The usage context is mostly implied rather than prescribed.

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

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

Annotations already mark the tool read-only and idempotent; the description adds important behavioral caveats: the network is mostly sample data, demo entries are named [DEMO] and flagged is_demo, and the agent should verify before acting. The schema further discloses that radius_miles and availability_window are accepted but not applied, providing additional transparency beyond the annotations.

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

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

The description is compact and front-loaded: it states the purpose first, then the critical demo-data warning, then the access note. Every sentence earns its place, and the warning is prominently capitalized without being verbose.

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

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

For a 6-parameter search tool with no output schema, the description covers the criteria, the ranking nature of results, the demo-data limitation, and key non-applied filter caveats. It does not explain the ranking order or exact return fields beyond is_demo and radius_miles_applied, but the information provided is sufficient for an agent 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?

The description enumerates the parameter categories but adds little meaning beyond their names. Schema description coverage is 50%, and the schema itself carries the important semantics about location matching and non-applied filters. Undocumented parameters like price_band and max_results are mostly self-explanatory, but the description does not compensate for the coverage 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 states a specific action: 'return ranked candidate businesses from our supply network' given explicit criteria, which clearly defines what the tool does. It also distinguishes itself from sibling tools like get_status, check_compliance, and send_message by being the business-search/resource 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?

The description makes the use case clear: use it when you need candidate businesses matching vertical, location, capability, price band, or availability window. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it over the listed 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?

The description discloses that it requires a key and is free, but annotations already provide readOnlyHint=true, which covers the safety profile. It does not add substantial behavioral context beyond that (e.g., rate limits, pagination), so the score is at the annotation-covered 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 description is a single sentence that front-loads the core purpose, defines the scope, and adds a concise, relevant usage note. No filler or redundancy.

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

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

For a read-only tool with a fully documented schema and no output schema, the description adequately covers what the agent needs to know to invoke it. It could mention the need for either reference+business_number or conversation_id, but this is implied by the schema, so minor gap.

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

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

The schema coverage is 100%, so the schema fully documents all three parameters. The description adds minimal value beyond hinting that conversation_id is preferred, but it does not degrade since the schema is sufficient. Baseline 3 applies.

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

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

The description clearly identifies the tool as reading a two-way conversation thread and specifies its contents (state, messages, reply count). The verb 'Read' is explicit and the resource ('conversation thread') is unambiguous, and it differentiates from siblings like send_message and get_status by its scope.

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 implies usage for reading a conversation, and the parameter hints (preferred conversation_id, reference requiring business_number) provide clear context for when to use it versus alternatives. However, it does not explicitly state when not to use it or name sibling alternatives, so it's not a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context beyond annotations: the operation must be completed, and the call is free with no key required.

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?

One tight sentence plus a bracket note. Every element earns its place, and the core purpose is front-loaded before the access note.

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 retrieval tool with strong annotations, the description is mostly complete: it identifies what to pass, when it is valid, and the access requirements. It does not describe the return shape, but no output schema exists and the resource name 'OutcomeReceipt' is reasonably self-descriptive.

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

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

Schema coverage is 0% and the schema only says operation_id is a required string. The description adds context by tying operation_id to the completed operation whose OutcomeReceipt is requested, but it does not specify where the ID comes from or its format.

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 ('Retrieve') and a specific resource ('final OutcomeReceipt') for a 'completed operation'. This clearly distinguishes it from siblings like get_status, which would naturally map to intermediate status rather than the final receipt.

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 clear context: this is for retrieving the outcome only after an operation has completed. It does not explicitly name alternatives or exclusions, but the completed-operation condition is a meaningful usage signal.

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 only needs to add context. It adds that the operation is free, requires no API key, and applies to in-flight async operations, which provides useful behavioral context beyond the annotations.

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

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

The description is compact and front-loaded. The primary purpose is stated in one clear sentence, and the cost/auth note is appended succinctly. Every element earns its place.

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

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

For a simple, one-parameter, read-only status tool, the description provides enough to call it correctly: the target resource, the identifier, and the cost/auth constraints. It does not detail the output shape or possible statuses, and it does not explain what happens if the operation is not in-flight, but these are not critical for a basic status query given the annotations.

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 only specifies 'operation_id' as a string with no description, so the description carries the semantic burden. It clarifies that operation_id references an in-flight async operation and that the tool queries its state, which gives the parameter meaningful context. It could be stronger by explaining how to obtain the operation_id, but it is adequate.

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

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

The description clearly specifies a verb ('Query'), a resource ('the current state of any in-flight async operation'), and the key identifier ('operation_id'). It also implicitly differentiates from the sibling 'get_outcome' by focusing on in-flight operations rather than completed outcomes.

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 clear context: use this when you need the current state of an in-flight operation identified by operation_id. It also notes the operation is free and requires no key. It does not explicitly mention exclusions or alternatives, but the usage context is 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?

With only bare boolean annotations, the description adds meaningful behavioral detail: it is async, costs $0.03 per call, durably records opt-outs, and does not auto-execute other actions. This goes well beyond the annotations and tells the agent what side effects to expect.

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?

One dense, front-loaded sentence conveys purpose, scope, side effects, and async behavior, with compact bracketed metadata for cost and continuation. No filler or repetition of schema details.

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 async tool with no output schema, the description covers selection and high-level behavior well, but it is incomplete on parameter details and the actual shape of suggested_action. The pointer to get_outcome helps, but an agent still lacks enough information to confidently construct all inputs or parse the result.

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

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

Schema description coverage is only 29%, so the description carries the burden of explaining parameters, but it adds little about smb_id, sender, received_at_iso, or inbound_channel. The intent list and mention of raw_message provide some context, but most parameter semantics are left to inference from names.

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 and resource ('Classify an inbound message... and get a recommended next action'), enumerates the intent taxonomy, and clarifies that it only recommends an action rather than executing one. This makes it clearly distinct from execution-oriented siblings like send_message or 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 description gives clear context: use this when a raw inbound SMB message needs intent classification and a suggested next action. It stops short of explicitly naming alternatives or when-not-to-use conditions, but the 'async→get_outcome' pointer and 'nothing else is auto-routed or auto-executed' provide practical 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?

Annotations already declare idempotentHint=true, and the description reinforces it with 'calling twice returns the same smb_id.' It adds valuable context beyond annotations: the free/requires-key note, the 12-platform detection list, and the honest failure behavior of schedule_appointment on non-Cal.com platforms. It doesn't fully detail side effects or auth requirements, but the idempotency and failure transparency are strong additions.

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 dense but efficient, packing purpose, limitations, platform list, idempotency, and cost into three sentences. The first sentence front-loads the core purpose. Slight redundancy with the idempotentHint annotation and the platform list could be trimmed, but it earns its place by giving concrete routing 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 tool with 8 parameters, no output schema, and a complex platform-detection behavior, the description covers the key operational facts: what it returns (smb_id), idempotency, platform support, and the critical schedule_appointment limitation. It doesn't describe the output shape or error cases, but the core call-and-routing context is complete enough for an agent to select and 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 88%, so the schema already documents most parameters well. The description adds context for booking_url (must point at one of the 12 supported platforms) and mentions vertical inference, but it doesn't add much beyond the schema. Baseline 3 is appropriate because the schema carries the heavy lifting.

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 ('Turn a public booking URL into a callable smb_id') and names the downstream tools it feeds (send_message, capture_lead). It also distinguishes itself from schedule_appointment by explicitly noting the Cal.com limitation, which separates it from a sibling tool. This is a clear, resource-specific purpose statement.

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

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

The description explicitly says when to use this tool (to convert a booking URL into an smb_id) and when not to rely on it (schedule_appointment only completes on Cal.com bound to one connected account; the other 11 platforms always fail). It also names the alternative schedule_appointment and the failure mode, giving an agent 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by mentioning 'Zero upstream cost, no key required' and the data coverage range (2020-2026). It also specifies the sorting behavior (by dollar amount), which is useful beyond the annotations.

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

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

The description is compact, front-loaded with the core action, and each sentence adds relevant information (API source, output fields, cost, key requirement, data range). No wasted words.

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 2-parameter read-only tool with no output schema, the description covers the essentials: what it returns, the data source, and constraints. It does not cover error handling or pagination, but these are minor for this use case and annotations already cover the safety profile.

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 parameters are already documented. The description adds minimal extra meaning, only reiterating the sorting by award amount for max_results and the search intent for company_name. This is within the baseline for full 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 states a clear verb ('Search') and resource ('US federal contract awards by company name') and lists the specific output fields. It is distinct from the sibling tools (which appear unrelated to contract lookup) and leaves no ambiguity about what the tool does.

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

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

The description clearly conveys when to use the tool (for US federal contract awards by company) and implicitly that it is for read-only lookups. However, it does not explicitly name alternatives or state when not to use it, but given the sibling tools are unrelated, the context is sufficient.

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

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

The description reveals non-obvious behavior not captured by annotations: the product value is echoed back and never checked against export-control lists, and a controlled item to an unrestricted destination returns 'partial', never 'clear'. It also commits to never fabricating a tariff rate, clear status, or restricted status, which is valuable behavior disclosure.

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 packs critical caveats into a compact paragraph. The all-caps emphasis and pricing note add noise but each clause contributes to accurate use.

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?

In the absence of an output schema, the description still hints at possible return statuses ('partial', 'clear') and explicitly disclaims fabrication of statuses/rates. It does not give a full output shape or error semantics, but it is sufficient for an agent to set expectations and 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics by stating that the product parameter is only echoed and not classified or screened. This clarifies the role of the product argument beyond the schema's generic 'Product name or 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 clearly frames the tool as a cross-border screening service for destination country and parties, and explicitly states it does not classify the product or provide export-control clearance. This distinguishes it from export-control tools, though the phrasing 'cross-border screening' remains somewhat generic.

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 explains when not to rely on the tool ('Not an export-control clearance -- classify HS/ECCN yourself') and what it will never do, which guides selection. It does not name an alternative sibling tool such as screen_sanctions or check_compliance, but the context is clear enough.

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 flags (readOnlyHint false, idempotentHint false, etc.) and do not explain behavior. The description adds meaningful operational details: no human action required, immediate usable key, honest not_configured failure mode, and free/no-key prerequisite. This materially helps the agent predict what will happen when it calls the tool.

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 dense and front-loaded with purpose and the key decision-relevant details. Only minor redundancy exists, such as repeating 'free-tier' and '[free, no key]', but each sentence otherwise contributes useful 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 tool with four required parameters and no output schema, the description covers the main invocation context, auth requirement, and a distinct failure branch. It does not specify the exact shape of the returned key or error, which is a small gap given there is no output schema to fill it.

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

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

Schema coverage is 100%, so the baseline is 3. The description explains the overall cryptographic proof flow using the parameters, but it does not add per-parameter meaning beyond the schema, which already documents agent_id, timestamp, nonce, and signature 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 uses a specific verb-resource pair ('mint API key') and immediately scopes it: self-serve, free-tier, for agents without an email inbox. It also states the authentication mechanism (HMAC-SHA256 with the MACHINE_MINT_SECRET), making it clear what this tool uniquely does relative to the unrelated sibling tools.

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

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

It explicitly names the intended user (an autonomous agent with no email inbox) and tells the agent to call once and branch on the not_configured failure before planning. It does not name alternatives or state when not to use it, but no sibling appears to offer key issuance, so this is a minor gap.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it returns exact prices when fixed, min/max ranges when variable, does not promise accuracy, and requires no API key ('[free, no key]'). 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?

Three focused sentences with no filler. The first sentence front-loads the core purpose, the second explains the exact-vs-range behavior, and the third adds a crucial caveat plus auth note. Every sentence earns its place.

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

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

The description covers what the tool returns, how pricing varies, and the free/no-key requirement. With no output schema, the return-value description is useful and mostly sufficient. Minor gaps remain around expected operation naming and the exact output shape, but the tool is simple enough that this is not a major deficiency.

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 you would pass to the operation,' and the description reinforces the 'proposed call' idea. However, the operation parameter is only a bare string with no allowed values or format, and the description does not elaborate on how operations are specified. Schema coverage is exactly 50%, so the description only partially compensates.

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 ('Return') and a precise resource: cost, latency, and success-probability estimates for a proposed call before execution. This clearly distinguishes it from siblings like get_outcome, get_status, or verify_company_record, which address different concerns.

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 clearly signals this tool is for pre-execution estimation ('before execution') and cautions that accuracy is not promised, directing the user to cost_range. It does not explicitly name alternatives or state when not to use it, but the context is clear enough given the sibling set.

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 (destructiveHint=true, readOnlyHint=false), the description discloses the honest failure mode (booking_destination_unmapped with no charge), the no-fabricated-confirmation guarantee, per-call pricing, and the async handoff to get_outcome. This is rich behavioral context that the 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 compact: purpose first, then binding/failure conditions, non-Cal.com caveat, then cost and async metadata in brackets. Each sentence adds unique information, and the front-loading makes it easy to scan. Minor repetition of 'fails honestly' is acceptable.

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 the key contextual constraints: binding prerequisite, failure code, no-charge behavior, non-Cal.com limitation, pricing, and async retrieval via get_outcome. With no output schema, the async pointer is essential. It could be more explicit about parameter requirements, but the schema's 'Required for cancel' note partially covers 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 25%, so the description carries the burden of explaining parameters. It names the three action values (already in the enum) and ties success to the smb_id's booking link, but it does not clarify customer, requested_time, service, or notes beyond their schema structure. This leaves a significant 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 pairing—'Check availability, book, or cancel via Cal.com'—that precisely captures the tool's lifecycle. It also distinguishes itself from siblings like check_booking_link by covering the full scheduling workflow and adding a binding condition that scopes when it applies.

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 clearly states the prerequisite (booking link bound to the connected Cal.com account) and the non-Cal.com limitation, giving agents a solid sense of when the tool will succeed or fail. It does not explicitly name alternative tools or say 'use X instead,' so it stops short of full when/when-not 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states the tool never fabricates a match or clear, instructs the agent to check lists_screened, and explains the reason_code 'partial_screening' behavior when a source fails. This is exactly the kind of non-obvious runtime behavior an agent needs to interpret results correctly.

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, then adds critical exclusions and behavioral rules. The pricing note is slightly tangential but useful for an agent deciding whether to call. Every sentence earns its place; a small deduction for the pricing aside being somewhat out of place in a tool description.

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

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

For a read-only screening tool with no output schema, the description covers the essential behavioral contract: which lists are screened, which are not, how to interpret partial failures, and the no-fabrication rule. It doesn't describe the exact return shape, but the description's guidance on lists_screened and reason_code partially compensates. Given the tool's complexity and the absence of an output schema, this is strong but not perfect.

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 context about the screening scope and result interpretation, but it doesn't add parameter-specific meaning beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 ('screening') and resource ('name/entity against sanctions lists'), and enumerates the exact lists covered (OFAC SDN, EU consolidated, UK FCDO). It also explicitly excludes the UN Consolidated List, which distinguishes it from any generic sanctions-screening sibling and prevents an agent from assuming broader coverage.

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 context: free screening of a name/entity against sanctions lists, with a clear exclusion (UN list not screened) and a behavioral rule (never fabricate a match or clear; check lists_screened; reason_code 'partial_screening' if any source failed). It also notes quota/pricing, which helps an agent decide when to call it. While it doesn't name a specific alternative sibling, the exclusions and conditions are strong enough to guide selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by disclosing the internal check count (6), the aggregate pass/fail nature, and the free/no-key requirement, which are not in the annotations.

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

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

The description is compact and front-loaded: it states the core function first, then the limitation, then the use case, then the free/no-key note. Every sentence earns its place with no redundancy.

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

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

For a zero-parameter, read-only health probe with no output schema, the description covers the essential information: what it checks, what it reports, what it does not do, and when to use it. The only minor gap is not describing the exact output format, but that is not critical for a simple health probe.

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

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

The tool has zero parameters, so the schema is trivially complete. The description adds no parameter details because none are needed; the baseline of 4 for zero-parameter tools applies.

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

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

The description clearly states the tool's function: it runs 6 internal checks and reports how many passed, confirming the server is up. It explicitly distinguishes itself from per-tool probing, which differentiates it from sibling tools like get_status or 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 says to use it to verify connectivity before production use, which gives a clear context. It does not explicitly name alternative tools or state when not to use it, but the 'does NOT probe each tool individually' exclusion provides useful 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 already declare readOnly=false, destructive=true, and idempotent=false, and the description adds substantial value beyond them: channel failure modes (unconfigured SMS/voice), immediate send with no scheduling, a non-bypassable multi-jurisdiction compliance gate, pricing, and an async→get_outcome handoff. The idempotency_key schema detail complements, not contradicts, the idempotentHint=false annotation.

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

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

Every sentence carries distinct information: scope, live channels, non-wired channels, immediacy, compliance gate, pricing, and async routing. The purpose is front-loaded and the bracketed tags ([from $0.02/call] [async→get_outcome]) at the end are highly skimmable. No wasted words.

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 7-parameter, no-output-schema tool, the description covers channels, failure behavior, compliance constraints, cost, and the async outcome path — quite complete. It does not describe the success receipt/return shape (which matters since there is no output schema), nor does it route to send_transactional_confirmation, so it is not a 5.

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 57%, so the description must partially compensate. It does add meaning for the channel enum (sms/voice will fail; whatsapp/email are live) and for message_type ('marketing' requires recorded consent). But it does not clarify recipient construction (id_type/id_value semantics), content.template_vars usage, or the truncated 'marketing is allowed only…' schema note.

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+resource ('Send a message on behalf of an agent's user or an SMB') and names the live channels (WhatsApp/email). It is clear but does not differentiate from the close sibling send_transactional_confirmation, which likely overlaps in scope, so it falls short of a 5.

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

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

Provides clear context and explicit when-not guidance: SMS/voice are 'NOT wired' and fail with channel_not_configured, and marketing without recorded consent produces a compliance_violation receipt. However, it never mentions the alternative tool send_transactional_confirmation or says when to prefer it, so it lacks the explicit alternative routing needed for a 5.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so mutation is known. The description adds value by explaining idempotency (replay returns original receipt, no re-charge) and honest failure on unconfigured channels, which are important behavioral traits beyond the annotations. However, it does not mention cost implications beyond the $0.02/per_call tag, which is minimal. 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 a compact three-sentence block that front-loads the core purpose and then adds crucial behavioral details. Every sentence carries weight: purpose, fallback/honest failure, idempotency and pricing/asynchronous pattern. No fluff or redundancy.

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

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

Given the tool's moderate complexity (5 params, nested objects, enums) and lack of output schema, the description is nearly complete. It explains idempotency, cost, async pattern, and type-specific data. Minor gaps: exact response format is not specified (no output schema), and the 'reminder' type is not described, but the description covers enough for a competent agent to invoke correctly.

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

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

Schema coverage is only 40%, so the description must compensate. It directly explains 'data' is type-specific (e.g., otp_code, appointment_time) and clarifies 'idempotency_key' semantics (24h replay returns original receipt). This adds meaning beyond the schema. However, it doesn't detail 'recipient' or 'preferred_channel' beyond the schema, but those are self-evident. Overall, it compensates well for the 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 explicitly names the tool as 'Idempotent transactional messages' and enumerates concrete use cases (OTPs, booking confirmations, payment receipts, cancellation notices), clearly distinguishing it from the sibling 'send_message' which likely handles general messaging. The specific verb 'send' and clear resource scope make the purpose 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 implies usage for transactional messages and briefly mentions channel fallback behavior, but it does not explicitly state when NOT to use this tool or name alternatives like 'send_message' for non-transactional messages. The context is clear from the examples, but lacks explicit exclusions.

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 read-only and idempotent behavior. The description adds value by clarifying this never contacts the business and that the data reflects a stored record ("when the record was last verified"). This is useful context beyond the annotations.

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

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

The description is two concise sentences, front-loaded with the core action and output, followed by a clarifying behavioral note. No filler or redundant detail.

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 names the returned data categories (contact channels, capabilities, last verified timestamp). It sufficiently sets expectations for a simple lookup tool, though it could clarify the optional capability parameter's role.

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 full burden for parameterscy. It mentions 'a business' and 'capabilities' but does not explicitly explain what `smb_id` should contain or how `capability_to_verify` affects the lookup. The optional parameter's meaning remains ambiguous.

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 is for looking up known business information in the supply network, with specific outputs named (contact channels, capabilities, last verified record). The explicit 'DIRECTORY LOOKUP - it does not contact the business' removes ambiguity about whether this is a live verification or a passive 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?

The description gives clear usage context: it is a read-only directory lookup, and explicitly says it does not contact the business. It does not name alternative sibling tools for comparison, but the exclusion is enough to prevent obvious 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 declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral detail beyond that: it names the two registries queried, highlights that it returns an honest not_found with sources when absent, and mentions the free quota and pricing. This goes well beyond the annotation hints and gives the agent a clear model of how the tool behaves under all outcomes.

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 sentence earns its place: purpose, registry sources, full return field list, non-fabrication guarantee, and cost model. It is front-loaded with the core action and immediately informs the agent of the most critical behavioral trait (honesty). No filler or redundancy.

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

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

Given that there is no output schema, the description compensates by listing every return field. It also covers failure behavior (not_found), sources queried, and cost. For a read-only lookup with simple parameters and clear behavior, nothing critical is missing – an agent has everything needed to correctly invoke and interpret 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add any parameter-specific semantics beyond what the schema provides; it only implicitly references name and LEI in the context of the registry output. With full coverage, a baseline score 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 states a specific verb ('lookup'), a precise resource (official company registry records via GLEIF and SEC EDGAR), and enumerates the returned fields (legal name, LEI, status, jurisdiction, etc.). It also explicitly declares what it will never do ('never fabricates'), which distinguishes it from other tools by setting clear expectations.

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 does not explicitly name alternative tools or conditions for choosing this one, but the sibling list contains no similar lookup tools, so the absence of explicit exclusion is acceptable. The description does provide strong contextual cues about when it is appropriate: it is a free/live lookup with honest not_found behavior, which helps the agent decide to use it for authoritative registry queries. However, it stops short of stating 'use X instead' or 'do not use when Y'.

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