Agent Broker

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

Goes well beyond the annotations by disclosing deployment unavailability, a per-call cost, a jurisdiction-based recording-consent compliance gate, and the async continuation pattern. Annotations already cover the safety profile (destructive/openWorld/non-idempotent), so this added operational context is a genuine supplement, though the return receipt of the async flow is not described.

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?

Front-loads the critical deployment-unavailability warning, then the purpose, then constraints and pricing. Bracket-heavy formatting makes it dense but each bracketed segment (availability, cost, async) carries distinct, decision-relevant information with 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 an 8-parameter mutating async tool with no output schema and no annotations covering return values, the description supplies the missing operational pieces: availability, cost, consent gating, and the get_outcome follow-up. It does not explain the receipt/return shape, leaving 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 88%, so the schema already documents nearly every parameter. The description only reinforces 'give a plain-language objective' and does not add format, precedence (smb_id vs business_phone), or value-range guidance beyond the schema, matching the baseline for high 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?

States a specific verb (place a conversational voice-AI phone call), the target (a business, on a consumer's behalf), and the operating model (give a plain-language objective; it navigates the call and extracts the answer). This is clearly distinguishable from siblings like send_message or get_outcome.

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

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

Gives clear context: it is business-directed (B2B), less restricted than calling consumers, and the async→get_outcome handoff tells the agent what to call next. It does not explicitly say when to prefer this over send_message or escalate_to_human, so it stops short of full alternative routing.

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

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

Annotations only declare the safety profile (readOnly=false, openWorld=false, idempotent=false, destructive=false). The description adds material traits beyond that: dedup semantics on (smb_id, phone or email), the storage destination and the fact that the business is NOT notified, per-call cost with the 'not charged while no payment rail' caveat, async result retrieval via get_outcome, and beta status. 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?

Front-loaded with the core purpose, followed by tight bracketed metadata (cost, async routing, beta). Every clause carries information; the bracketed tags are slightly cryptic but dense rather than padded.

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 mutation tool with no output schema, the description covers the essentials: what it does, where data lands, who is notified, cost, and that the result is retrieved asynchronously via get_outcome. The consent_record_id requirement for downstream send_message is handled in the schema. Minor gaps remain around error/validation failure behavior, but nothing critical to calling 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 50%, so the description must carry weight, and it does: the dedup key '(smb_id, phone or email)' gives real meaning to smb_id and the prospect's contact fields that the schema does not. It does not elaborate on source or idempotency_key (the latter is documented in the schema), so it adds value without fully closing 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?

States a specific verb and resource ('Structured intake of a prospect into an SMB's funnel') plus the dedup key and validation behavior, and explicitly disambiguates the destination ('AgentBroker's own lead funnel, NOT the business's CRM'). An agent can distinguish this from siblings like handle_inbound or send_message without opening a schema.

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 establishes the operating context clearly: it's AgentBroker's funnel, not the business's CRM, and the business is not notified. The '[async→get_outcome]' tag routes the agent to the follow-up tool, and the pricing note sets expectations. It stops short of naming explicit when-not-to-use conditions against siblings (e.g., when to prefer handle_inbound), so it's clear context without 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 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 cover readOnly/idempotent/non-destructive, but the description adds substantive behavior: nothing is sent or changed, it is free with no key required, it runs the same rules as the live tools, and on failure it returns the exact rule plus remediation. That is genuine value beyond the structured hints.

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

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

Front-loaded with the key claim (free, instant pre-flight) and tight overall, though the check_booking_link analogy and the bracketed '[free, no key]' tag partially repeat points already made. Efficient but not maximally lean.

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 return contract and does so well: it states the outcome (permitted or not), names the failing rule, and points to the fix. Combined with the no-side-effect guarantee, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including the channel enum and auto-inference rules. The description adds no parameter-level detail (e.g. what content is scanned for), so the 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?

States a precise verb+resource ('runs the SAME TCPA/GDPR/CASL/CAN-SPAM/10DLC checks ... in preview mode') and explicitly distinguishes itself from the real send tools send_message and call_business. An agent immediately knows this is a dry-run gate check, not an 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?

Gives an explicit when-to-use condition ('pre-flight ... before you pay') and frames the alternative it de-risks (the paid send). The preview/no-side-effect framing tells the agent this is the correct pre-step rather than guessing.

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 cover the safety profile (destructive, not read-only, not idempotent), and the description adds material behavior beyond them: a ticket is written to the operator queue, no notification is sent, no response time is promised, the call costs $0.2, and it runs async. This is exactly the extra context an agent needs before a mutating escalation.

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?

Front-loaded with the action and its payload, then side effects, then bracketed cost/async/beta tags. Dense and largely waste-free, though the three bracketed tags are terse metadata that an agent must decode.

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 destructive, non-idempotent mutation with no output schema, the description covers side effects, cost, async follow-up via get_outcome, and beta status. It leaves the enum-valued reason and priority parameters unexplained, which is the main 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 coverage is only 20% across 5 params, so the description carries some burden. It enumerates the context bundle contents (transcript, prior actions, identifiers, recommended next step), partially compensating, but adds nothing about the reason enum values, priority semantics, or smb_id. Baseline 3 given partial 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?

States a specific verb ('hand off') and resource ('an in-flight task to a human operator') plus what the handoff carries (context bundle). This is clearly distinguishable from siblings like send_message or get_outcome.

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

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

'Hand off an in-flight task' plus the reason enum values imply when to reach for this over messaging siblings, and '[async→get_outcome]' points at the follow-up tool. It never states explicit exclusions or when NOT to escalate, so it stops short of 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?

Goes well beyond the annotations: discloses ~5s latency, that partial/search_in_progress means the call must be repeated, that an OSM outage yields a retriable 'temporarily unavailable' rather than fabricated rows, and that results are community-mapped and NOT verified by the provider. These are exactly the operational traits an agent needs and none are 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?

Front-loaded with the core verb+resource, then grouped caveats (data provenance, latency/status, failure mode, tags). Dense but nearly every clause carries information; the trailing '[free, no key] [beta]' tags are slightly cluttered but useful.

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 8 params, nested objects, and no output schema, the definition adequately covers provenance, retry semantics, latency, and the booking limitation, and points at result.search for ordering. It stops short of describing result fields or pagination, leaving a small gap for a discovery 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 75%, so the schema already carries most parameter meaning (radius_miles default/max, price_band scope, availability_window not applied). The description adds little parameter-specific detail of its own beyond the booking constraint tied to source rows, so the 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?

Specific verb+resource: 'Find real businesses near a place, sorted by distance', with the result ordering and the fact that sorting covers only examined rows made explicit. This cleanly separates it from siblings like verify_business, call_business, and capture_lead, which act on a business rather than discovering one.

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?

Implied context is present: it is the discovery step ('find real businesses'), and the caveat that source=openstreetmap rows cannot be booked hints at a downstream booking/verification flow. However it never explicitly states when to prefer this over siblings such as verify_business, nor does it name any alternative or exclusion condition, so usage must be inferred.

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?

Goes well beyond the annotations by disclosing the bounded side effect ('Opt-outs are recorded durably; nothing else is auto-routed or executed'), the pricing model ($0.03/call, waived while no payment rail is on), async execution with get_outcome, and beta status. This reconciles the apparently read-only framing ('Classify') with readOnlyHint=false. It omits auth/permission requirements and any rate limit, which keeps it short of a 5.

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?

Purpose is front-loaded in the first clause, followed by the intent examples and bracketed operational tags. Every element is information-bearing, though the dense bracket syntax ([$0.03/per_call] [async→get_outcome] [beta]) is terse at the cost of scannability.

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, nested-object tool with no output schema, the description covers side effects, cost, and async retrieval of results, which is most of what an agent needs. It does not describe the shape of the suggested_action receipt, and with no output schema that return-value gap is only partially bridged.

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 is expected to compensate for the seven parameters, yet it says nothing about smb_id, raw_message, sender, inbound_channel, or received_at_iso. The listed intents (booking request, cancellation, opt-out, inquiry, complaint) describe the classification output, not input semantics, so they do not fill 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?

States a specific verb ('Classify') and resource ('an inbound message for an SMB') plus the deliverable ('a suggested_action'), and explicitly bounds scope with 'nothing else is auto-routed or executed'. It does not name any sibling, but 'handle_inbound' is readily distinguishable from send_message, capture_lead, or escalate_to_human.

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 supplies one routing cue ('async→get_outcome') and frames the classification as advisory ('treat the intent as a hint'), which implies when to trust the result. However it never states when to use this tool versus capture_lead, escalate_to_human, or send_message, so the agent must infer the placement from the description alone.

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 cover readOnlyHint=false, idempotentHint=true, openWorldHint=false, destructiveHint=false. The description adds real value beyond these: it discloses the scheduling capability gap per platform, states idempotency semantics ('calling twice returns the same smb_id'), lists the 12 supported platforms, and flags cost ('free') and rate limiting ('[limited]'). This is exactly the kind of behavioral context annotations can't express.

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?

Front-loaded with purpose, but the sentence about schedule_appointment completing only on Cal.com is dense and syntactically awkward ('only completes on Cal.com bound to our one connected account — the other 11 always fail schedule_appointment honestly, uncharged'). The trailing bracket tags ([free, requires key] [limited]) are cryptic stubs rather than integrated information. Information density is high but structure suffers.

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-param import tool with no output schema, the description covers platform support, idempotency, cost, rate limits, auth requirement, and downstream-consumer semantics. The main gap is it does not describe the returned smb_id shape or any error semantics when the URL is on an unsupported platform — relevant since there's no output schema to fall back on.

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 carries the bulk of parameter documentation. The description adds little parameter-level detail beyond the schema except the platform-count constraint on booking_url. Baseline 3 is appropriate when the schema does the heavy lifting and the description does not compensate further.

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?

Clear specific verb+resource: 'Turn a public booking URL into a callable smb_id'. Names the consumer tools (send_message, capture_lead), which distinguishes it from siblings. Lacks a direct contrast to check_booking_link, which is the nearest sibling, but the operation is unmistakably distinct.

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?

Strong routing guidance: states the smb_id is used by send_message and capture_lead, and warns that schedule_appointment only works on a Cal.com account bound to the service (the other 11 platforms fail). That's actionable when/when-not. No explicit mention of check_booking_link as an alternative for pre-flight validation, which would have made it 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=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?

Goes well beyond the annotations (which only declare read-only/idempotent/non-destructive) by disclosing the crucial behavioral quirk: a controlled item to an unrestricted destination returns 'partial', never 'clear,' and the product is echoed back without verification. The 'Never fabricates a tariff rate, a clear, or a restricted status' guarantee is genuinely useful trust context.

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?

Front-loaded with the core operation and its most important caveat in a single dense block, with the free/no-key note placed last. Slightly run-on and repetitive (the 'never a clear/restricted status' idea appears twice) but no sentence is wasted.

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

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

There is no output schema, so the description usefully pre-empts the key output ambiguity by explaining 'partial' vs 'clear' statuses. It does not fully describe the response shape or party-screening result format, but covers the decision-critical nuance for a read-only tool whose annotations already carry 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 schema already documents all five parameters and the baseline is 3. The descriptionadds only indirect meaning (product is echoed, destination/parties are screened) but no per-parameter syntax or format guidance 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 states a specific verb and resource: 'cross-border screening of destination and parties,' and sharply delimits scope with 'DOES NOT CLASSIFY THE PRODUCT.' It differentiates itself conceptually from export-control and tariff siblings, though it never names an alternative like screen_sanctions or check_compliance, so an agent must infer the routing.

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?

Clear context is given for when this is appropriate (free cross-border destination/party screening) and strong exclusions ('Not an export-control clearance -- classify HS/ECCN yourself'). However, no sibling tool is named as the alternative path, so the agent must reason about which other tool supersedes this one.

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 say it is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds substantial context beyond that: the required HMAC secret, the two named failure modes (invalid_request, not_configured), and the 60s freshness window implied by the timestamp parameter.

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?

Front-loads the core action and signing scheme, then tacks on refusal codes and the alternative endpoint. Dense and largely waste-free, though the bracketed tags ('[free, no key] [limited]') are cryptic 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 four-required-parameter mutation with no output schema, it covers auth requirements, failure cases, and the alternate path. It stops short of describing what the minted key response looks like, which is a minor gap given there is no output schema.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema. The description restates the signature construction but adds no format or constraint detail the schema lacks, so the 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?

States a specific verb and resource ('Mint a free-tier API key without email') and the exact mechanism (HMAC-SHA256 over agent_id + timestamp + nonce). No sibling tool does anything comparable, so the agent can place it immediately.

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

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

Gives a clear precondition (requires MACHINE_MINT_SECRET) and routes to an explicit alternative when the secret is absent ('No secret: use POST /keys/request'). It does not spell out the broader when-to-use case versus the other key/booking siblings, but the fallback routing is genuinely useful.

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?

Annotations only supply the generic safety profile (destructive/openWorld/non-idempotent); the description adds concrete failure semantics (booking_destination_unmapped, honest failure instead of fabricated confirmation), the no-charge guarantee, platform limitations, and async behavior. This is exactly the beyond-annotation context an agent needs.

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?

Front-loaded with the core verb set, then dense but each clause carries distinct information (precondition, failure mode, platform limit, price, async tag). Slightly overloaded with bracket tags, but no wasted sentence.

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

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

With no output schema, the description correctly focuses on behavior and failure modes and is fairly complete for a complex, destructive, async tool. Its one real gap is the undocumented parameter surface, which the description leaves entirely to a low-coverage 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 only 25% across 8 params with nested objects, yet the description explains no individual parameter. It implies the action set and no-charge behavior but never clarifies smb_id, service, customer, requested_time, or how the idempotency_key interacts with the 24h replay.

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 set (check availability, book, cancel) against a specific resource (Cal.com appointment) and the enum matches exactly. It is immediately distinguishable from siblings like check_booking_link or 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?

Gives a clear precondition (the SMB's imported booking link must be bound to the one connected Cal.com account) and routes async callers to get_outcome via '[async→get_outcome]'. It does not, however, say when to prefer check_booking_link or import_booking_url over this tool.

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

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

Annotations already declare read-only/idempotent/non-destructive, but the description adds substantial behavioral context beyond them: it will never fabricate a match or a clear result, it exposes lists_screened for verification, and it defines the partial_screening failure mode. The explicit exclusion of the UN list for licensing reasons is exactly the kind of coverage caveat annotations cannot convey.

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

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

Front-loaded with the core action and target lists, then caveats, then a compact cost/key tag. Dense and effective, though the heavy capitalization and multi-clause sentences make it slightly harder to scan than it needs to be.

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 naming key return signals (lists_screened, reason_code values) and the partial-result contract. It does not fully describe the shape of a hit record, but the critical interpretation guidance an agent needs is present.

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

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

Schema description coverage is 100%, so name/type/country are already documented with examples and enum values. The description adds only the script hint (Latin or Arabic), which is largely mirrored in the schema, so the 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?

States a specific verb (screen) and resource (name/entity) and enumerates the exact lists consulted (OFAC SDN, EU consolidated, UK Sanctions List). It also carves out scope precisely by naming what is NOT covered (UN Consolidated List), so an agent can distinguish it from siblings like check_compliance 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?

Gives clear context for when the tool applies (screening a name/entity, Latin or Arabic script) and useful operating guidance about checking lists_screened and treating reason_code 'partial_screening' as non-clear. It does not, however, name an alternative sibling tool or state when to prefer a different screening/compliance tool, so it stops short of full 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, 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?

Goes well past the annotations: a non-bypassable compliance gate (TCPA/GDPR/CASL or the service default), a named rejection artifact (compliance_violation receipt), cost behavior ($0.02/call, not charged while no payment rail is on), async execution requiring get_outcome, and deployment-limited channels. These are exactly the side effects and failure modes an agent must know before invoking a destructive, open-world send.

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?

Front-loaded with the core action and scope in the first clause, so an agent gets the gist immediately. The trailing bracket block (pricing, async routing, deployment limits) is dense and slightly cluttered, but each item carries operational value rather than filler.

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

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

For a 7-parameter, nested-schema, highly regulated tool with no output schema, the description covers the decision-critical context: compliance gating, rejection behavior, cost, async outcome path, and channel availability. It does not describe the success receipt shape or authentication/permission requirements, which would fully round it out.

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 57% schema coverage, the description meaningfully compensates: it enumerates the usable channels in prose (WhatsApp/SMS/email/voice with availability caveats), ties message_type to consent rules, and explains the regulatory dimension behind country_code routing. It says nothing about business_id, on_behalf_of, idempotency_key, or template usage, so a few parameters remain schema-only.

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 plus scope: send a single message on behalf of a user/SMB across WhatsApp, SMS, email, or voice, immediately with no scheduling. The channel enumeration and compliance framing make the operation unambiguous. It does not name the sibling that overlaps most (send_transactional_confirmation), so the agent can't fully disambiguate from siblings on this description alone.

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?

Gives real routing conditions: messages are immediate (no scheduling), marketing is rejected without recorded opt-in on most channels, US marketing email follows CAN-SPAM, and async results are routed to get_outcome. It also flags deployment limits (SMS and Voice unavailable here), which prevents an agent from selecting an unusable channel. No explicit 'use X instead of Y' comparison against send_transactional_confirmation or check_compliance is given.

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?

Adds substantial behavior beyond the annotations: channel fallback semantics, an explicit honest-failure guarantee ('fails honestly rather than reporting a delivery that did not happen'), per-call cost and the condition under which it is not charged, and async retrievability. Minor tension: the description calls the messages 'Idempotent' while idempotentHint=false, though the schema's idempotency_key (24h replay) reconciles this as key-scoped idempotency rather than default 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?

Information-dense and front-loaded: the artifact types come first, then fallback semantics, then cost/async/deployment brackets. The bracketed shorthand is efficient but slightly telegraphic; every element still 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?

With no output schema, the description usefully supplies the async retrieval path (get_outcome), the cost model, honest-failure semantics, and the SMS unavailability — enough for correct invocation. Residual gaps are the recipient/data payload expectations left to a schema that is only 40% documented.

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

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

Schema description coverage is only 40% across 5 params with a nested recipient/data object, so the description must carry more weight than it does. It does add meaning for channel behavior ('falls back across configured channels') and idempotency, and its type list overlaps the confirmation_type enum, but it never explains the data payload shape or recipient fields.

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

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

States a specific verb+resource ('transactional messages') and enumerates the concrete artifact types (OTPs, booking confirmations, payment receipts, cancellation notices), which maps directly onto the confirmation_type enum and separates it from the generic send_message sibling. An agent can identify the tool's domain without opening the schema.

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 operating context: it routes the agent to get_outcome for async results ('async→get_outcome') and states an exclusion ('Not available on this deployment: SMS'). It does not, however, explicitly contrast this with the sibling send_message, so the when-to-use boundary between transactional and general messaging is left to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world behavior, so the bar is low. The description still adds genuinely new facts: that it performs no contact, the acceptable id namespace, and cost/access tags '[free, no key] [limited]' signaling no credentials but constrained availability. The '[limited]' tag is left undefined, which keeps it from a 5.

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?

Front-loads the lookup scope, then the disambiguating negative, then the id constraint and cost tags - a sensible ordering with no filler sentences. The bracketed tags are terse and functional, though '[limited]' is vague enough to cost a point.

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 naming the returned content (contact channels, capabilities, last verification), and annotations carry the safety profile. The remaining gap is the unexplained capability_to_verify parameter, which an agent may need 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 0%, so the description must carry both parameters. It does document the smb_id namespace constraint ('Supply-network ids only, not osm:... ids'), which is real added meaning. However, capability_to_verify is never explained - no hint of what capabilities exist or what verification means for them - leaving half the parameters undocumented.

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 ('Look up what we know about a business in our supply network') and enumerates the fields returned (contact channels, capabilities, last verification). It also draws the key boundary against siblings by declaring 'A DIRECTORY LOOKUP - it does not contact the business', which separates it from call_business without opening either schema.

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?

Gives clear context for when the tool applies: read-only directory inspection rather than outreach, and id-namespace restriction ('Supply-network ids only, not osm:... ids'). The alternative (call_business) is implied by the negation but never named explicitly, so an agent must infer the routing rather than being told 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely useful behavior beyond them: the two named upstream registries, the 'never fabricates' guarantee, and the explicit honest not_found response with sources queried. Note the tension with openWorldHint=false given it calls public external registries, though that is a borderline inconsistency rather than a direct contradiction.

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

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

Three dense sentences with the capability stated first, the sources second, and the honesty guarantee last; the [free, no key] tag is front-loaded at the end as a scannable marker. No filler or repetition of the title.

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 enumerating the returned fields and describing the not_found behavior, so an agent knows what to expect. The only shortfall is that lookup precedence between the optional lei and name parameters, and result format, remain unstated.

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 each of the three parameters carries its own description (lei = 20-char identifier for precise lookup, name = legal company name, country = ISO 3166-1 alpha-2 filter). The description does not add parameter-level detail, so the schema is doing all the work; baseline 3.

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 (verify/lookup) and resource (company official registry record), and names the exact data sources queried (GLEIF LEI registry, SEC EDGAR) plus the fields returned. An agent can separate this from siblings like screen_sanctions or check_compliance without opening any schema.

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?

Describes the context in which it applies (free, live lookups of corporate registration data) and the failure mode, but never states when to prefer it over the nearby siblings (screen_sanctions, check_compliance, map_trade_restriction) or what inputs make it inappropriate. Usage is 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.