Agent Broker

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

The description adds meaningful real-world behavior beyond the annotations: it places an actual phone call, is async ('async→get_outcome'), and costs money. This aligns with the destructiveHint/readOnlyHint annotations and gives the agent a realistic sense of side effects. It does not detail failure modes or retry behavior.

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

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

The description is reasonably front-loaded, leading with the core action and differentiator before cost and async behavior. The 'far less…' fragment and promotional tone ('THE differentiated capability') slightly reduce crispness, but the key usage points are covered in a compact paragraph.

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 conveys the primary outcome, async retrieval via get_outcome, and pricing. However, it does not explain failure/error behavior, idempotency or max-duration semantics, or when the call is considered complete. For a tool with external side effects and multiple schema parameters, richer operational context is missing.

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

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

The schema already describes the parameters well (e.g., business phone, objective, extract_fields, idempotency key). The description adds only the high-level guidance that the objective should be plain language and that the tool 'extracts the answer.' This is helpful but not a substantial addition over the rich 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 opens with a specific verb and resource: 'Place a conversational voice-AI phone call to a business... and return a structured answer.' It also clearly differentiates the tool from alternatives by emphasizing the core use case: reaching the 'tens of millions' of SMBs with 'no API and no booking page — only a phone number.'

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 gives clear context for when to use the tool — when the target business has no digital integration and only a phone number — and instructs the agent to provide a plain-language objective. It does not explicitly name sibling alternatives or state exclusions, 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?

This is notably transparent. It discloses that a write occurs ('stores in the SMB's AgentBroker lead funnel'), clarifies the side-effects are confined to AgentBroker not the CRM, exposes deduplication and validation behavior, flags the call as async leading to get_outcome, and states the cost per call. None of this is present in the annotations, so it adds real value.

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 sentences pack the essential distinctions: what it is, what it is not, and how it completes (async). No filler, no restating of parameter names without added meaning.

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

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

Covers scope, destination, dedup behavior, async nature, and cost — enough for an agent to decide to call it. It doesn't mention required fields (name) or the idempotency_key behavior, but those are already in the schema, so the incremental gap is small.

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 adds the crucial dedup rule on (smb_id, phone or email), which enriches the schema's bare phone/email fields. It doesn't mention source or idempotency_key, but the schema itself documents those, so the description need not repeat them.

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

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

The description opens with a specific action and object: 'Structured intake of a prospect into an SMB's funnel' — immediately clarifying what capture_lead does. It further disambiguates by explicitly stating this is AgentBroker's own lead store, not a write into the business's CRM, which separates it from any CRM-focused sibling.

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

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

The description gives clear context: use this for structured prospect intake with validation/deduplication reporters, and it explicitly states it is not a CRM write. It does not name an alternative tool, but the negative scoping plus async routing to get_outcome gives usable 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 carry readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is pre-declared. The description adds beyond that: preview mode, zero message delivery, no state changes, and informative output ('names the exact rule and how to remediate'). This aligns with the annotations and adds cost/de-risking context. No contradiction.

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

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

The key facts are front-loaded (free, instant, pre-flight, same gate, no side effects), but the description carries rhetorical filler like 'de-risk' and the 'SAME... gate' emphasis, and it trails off awkwardly ('...the same way check_booking_link… [free, no key]'), which reads as a truncated thought. It earns a middle score: dense but not clean.

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 the essentials: what it evaluates, in what mode, the safety profile, when to invoke it, and what the answer tells you (permitted, or exact rule + remediation). A fully explicit return structure or error-case discussion is absent, but the schema and annotations already carry the parameter and safety burden, so 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?

Schema description coverage is 100%, so the schema already documents all six parameters in detail, meriting the baseline 3. The description adds only marginal framing by grouping the parameters into the send tuple '(recipient, channel, message_type, content)', which reinforces but does not materially extend the schema's per-parameter explanations.

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 function ('pre-flight for the compliance gate') and a specific resource: the TCPA/GDPR/CASL/CAN-SPAM/10DLC gate also used by send_message and call_business. It explicitly contrasts preview mode with real sends ('NO message is sent'), and tells an agent exactly what question it answers ('whether a (recipient, channel, message_type, content) send would be permitted'). This distinguishes it clearly from siblings.

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

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

The description gives clear when-to-use context: 'de-risk a paid send' and 'BEFORE you pay for it', plus the free/no-key appeal. It contrasts with the actual-send tools (send_message, call_business) and alludes to a same-pattern sibling (check_booking_link), though that reference is truncated mid-sentence. It does not enumerate exclusions versus the sanction/restriction siblings, but the preview-vs-execute distinction is the load-bearing guidance.

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

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

Beyond the 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?

The description adds useful behavioral context: a $0.2 per-call charge and an async pattern with output retrievable via get_outcome. However, annotations mark destructiveHint=true, and the description offers no explanation of what side effects occur (e.g., task transfer, no local completion), leaving the risk profile to annotations alone.

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 sentence, no filler: it leads with the action and context bundle, then packs cost and async behavior. Every clause carries 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 5 parameters, a nested context object, and no output schema, the description covers orientation (cost, async, get_outcome) but not the full required context shape (e.g., operation_id, original_operation) or what the synchronous receipt looks like. The agent has to infer some required fields from schema names.

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% (just idempotency_key). The description compensates partially by listing context bundle fields—transcript, prior actions, identifiers, recommended next step—but says nothing about smb_id, reason enum, or priority, forcing the agent to rely on enum names and plain naming.

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 says the action: 'Hand off an in-flight task to a human operator' with a context bundle. This is specific and distinct from sibling tools like get_outcome or handle_inbound—no other tool names a human operator as the destination.

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 phrase 'in-flight task' implies this tool is for escalation during an ongoing task, and the async->get_outcome hint suggests a follow-up pattern. However, it never states when not to use it, nor names any alternative tool or a condition for skipping escalation.

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

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

The description goes beyond annotations by explicitly warning that the network is small and mostly sample data, and instructs the agent to check the is_demo field before acting. It also notes '[free, no key]' indicating no authentication required, which is useful context not present in annotations. Since annotations already declare readOnly and idempotent hints, the description adds value with the demo warning and free access.

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

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

The description is concise, with two sentences and a short tag. It front-loads the purpose and criteria, then adds the critical warning about sample data. Every sentence earns its place; no fluff.

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

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

For a search tool with no output schema, the description explains the output type (ranked candidates) and warns about data quality. It does not describe the structure of each candidate beyond the is_demo flag, but given the complexity of the input schema (nested objects), the description covers the key caveat. It also mentions availability_window as not applied, which is a significant behavioral note. A small gap: no mention of how ranking works, but that's likely acceptable.

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 description helps with some parameters. The description lists vertical, location, capability, price band, availability window as criteria, which adds clarity beyond the schema. However, it does not detail the format for nested objects like price_band or availability_window (though schema provides some info). It also flags that availability_window is not applied, which is critical and not in the schema description. Thus, description compensates well for the 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 purpose: return ranked candidate businesses from a supply network based on criteria. It lists specific filters (vertical, location, capability, price band, availability window) and the output type (ranked candidates). This distinguishes it from siblings like verify_business or check_compliance, which have different purposes.

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 searching for businesses), but does not explicitly state when NOT to use it or provide alternatives. However, it does mention the small network and sample data, which subtly warns about reliability. There is no explicit comparison to sibling tools, so the guidance is moderate.

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 destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it clarifies the tool only reads conversations the user started, and it discloses the '[free, no key]' property, which is useful operational context not present in the schema or annotations. It does not describe pagination or error behavior, but for a read-only conversation fetch, the added context is solid.

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, front-loaded sentence that states the action, the resource, and the return contents, followed by a short parenthetical about cost/auth. Every word earns its place; there is no fluff 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 read-only tool with 100% schema coverage and no output schema, the description is nearly complete. It tells the agent what it will get (state, messages, reply count) and the access requirement (free, no key). It does not explain the relationship between the three parameters (e.g., which to prefer), but the schema already documents that, so the description does not need to repeat it. A small gap is the lack of any note about what happens if the conversation is not found, but that is minor.

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 the 'two-way conversation thread you started' context and the '[free, no key]' note, but it does not add meaning about how the parameters relate (e.g., reference requires business_number, conversation_id is preferred). The schema already covers those details, 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?

The description states a specific verb ('Read'), a specific resource ('a two-way conversation thread you started'), and enumerates exactly what is returned: state, every message exchanged, and reply count. It also distinguishes itself from siblings by scoping to conversations the user started, which is not evident from the tool name 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?

The description gives clear context for when to use the tool: to read a two-way conversation thread you started. It does not explicitly name alternatives or exclusions, but the sibling list includes get_status, get_outcome, and check_compliance, and the description's focus on 'conversation thread' and 'messages' makes the usage context clear enough. It lacks an explicit 'use X instead when...' statement, so it falls 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?

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?

Annotations already indicate non-read-only, non-idempotent behavior, but the description adds critical details: opt-outs are durably recorded, no other auto-routing or auto-execution occurs, and there is a per-call cost. This goes beyond what annotations provide and clarifies side effects and boundaries, earning a solid 4.

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, tightly packed paragraph that leads with the primary action, then covers scope, side effects, cost, and async flow. Every sentence adds value and there is no filler, making it highly efficient.

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

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

The tool has no output schema, and the description only mentions that it returns a suggested_action. It does not describe the shape of that action, error handling, or retry semantics beyond the idempotency key in the schema. While the main purpose is clear, an agent might lack details on how to consume the result, so completeness is only average for a classification tool with multiple parameters.

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

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

Schema description coverage is only 29%, and the description does not compensate by explaining parameters beyond the schema. It mentions inbound message and intents but does not elaborate on the meaning of smb_id, raw_message, sender, or routing_rules. The idempotency_key and routing_rules have schema descriptions, but others remain undocumented in both schema and description, making parameter semantics weak for a low-coverage case.

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 classifies inbound messages and returns a suggested action, listing specific intents. It distinguishes itself by explicitly stating that opt-outs are recorded durably and nothing else is auto-executed, which separates it from sibling tools that might route or execute actions.

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 explains the tool is for classifying inbound messages and that the agent should act on the returned suggestion, while noting that only opt-outs are recorded automatically. It references the async nature and points to get_outcome, giving context for when to use it. However, it does not explicitly name alternative tools for related tasks, so it falls short of full 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 provide idempotentHint, readOnlyHint, destructiveHint, but the description adds valuable context: it states idempotency explicitly ('calling twice returns the same smb_id'), mentions free tier and key requirement, and implies side effects (returns an smb_id). It also provides the behavior of being able to use the result with other tools. Since it adds meaningful context beyond annotations without contradicting them, score a 4.

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 but packs essential information: purpose, supported platforms, outcome, idempotency, and note about free/key. Every sentence earns its place. The critical info (what it does) is front-loaded, and the idempotency note and free requirement are brief but important. It avoids fluff.

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

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

Given the tool's complexity (8 params, 1 required) and full schema coverage, the description needs to provide enough context for an agent to call it effectively. It explains the main output and use case, and the idempotency behavior. However, it does not explain what happens on failure (e.g., unsupported URL) or how to interpret the returned smb_id beyond being reusable. Since there is no output schema, a bit more on the return value or error handling would be helpful, but it's not critical. Score 4.

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

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

Schema description coverage is 100%, so the baseline is 3. The description itself does not explain individual parameters, but it explains the overall purpose and a key behavior (idempotency). However, it adds context to the booking_url parameter by listing supported platforms retaining the 12 platforms in the schema) and mentions optional overrides like business_name auto-extraction. Given the schema is already detailedais a plus, but the description could do more to clarify edge cases or parameter interactions.

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

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

Description clearly states it converts any public booking URL into an smb_id, lists supported platforms, and mentions idempotency. It distinguishes itself from siblings like schedule_appointment and check_booking_link by its specific action (importing a URL) and output (an smb_id that can be used with other tools). The verb 'import' plus the resource 'booking URL' 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 explicitly says the resulting smb_id can be used with schedule_appointment, send_message, or capture_lead, which tells the agent when to use this tool (when you have a booking URL and need an smb_id). It also notes it's idempotentandarerequires a key. However, it doesn't explicitly mention when NOT to use it or contrast with siblings like check_booking_link, so it loses a point.

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?

Annotations already flag readOnlyHint, idempotentHint, and destructiveHint. The description adds important behavioral detail beyond annotations: the product is never checked, it is only recorded and echoed back, and the tool returns reason_code 'partial' instead of 'clear' for controlled items. This materially shapes agent expectations.

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 somewhat rambling: it uses all-caps, mixes pricing into the main statement, and ends with a truncated 'Given a product and…' fragment. While informative, the formatting is messy and longer than necessary for an agent to parse, which hurts usability.

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 5-parameter tool with no output schema, the description covers core limitations (no product classification, result reason_code behavior) but does not describe the overall response shape or how to interpret findings beyond the 'partial'/'clear' contrast. That leaves some ambiguity for an agent deciding how to handle the result, especially in conjunction with sibling tools.

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

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

Schema coverage is 100%, but the description enriches parameter meaning, especially for 'product' by clarifying that it is recorded and echoed back and never classified. It also emphasizes the role of destination country and parties. No contradiction with schema, and this extra context is important for correct usage.

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 function: cross-border trade screening of the destination and the parties, and it clearly distinguishes itself from product classification/export-control clearance. It does not explicitly name sibling tools like check_compliance or screen_sanctions, but the scope and exclusions make its purpose clear.

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 not to use the tool (not for product classification/export-control clearance) and what it does cover (destination and party screening). It lacks a direct comparison to named sibling tools, but the exclusions and 'free in quota, then $0.02/call' wording give adequate usage context.

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

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

Annotations 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate that. It adds useful behavioral context: routing through native booking system, fallback to voice AI/web form, cost per call, and async completion via get_outcome. It also notes idempotency behavior in the schema, which is a strong behavioral 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 compact and front-loaded with the core purpose, then adds routing, cost, and async notes. Every sentence earns its place, though the cost and async notes could be seen as secondary. It is appropriately sized for a tool with 8 parameters and complex behavior.

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, nested objects, multiple actions, async behavior), the description covers the key operational aspects: routing, fallback, cost, and async completion. It doesn't explain return values, but there is no output schema and the async note points to get_outcome. The main gap is lack of explicit guidance on which parameters apply to which actions, but the schema's existing_appointment_id description 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 must compensate. It does mention the action types and the routing behavior, and the schema itself documents idempotency_key and existing_appointment_id. However, the description doesn't explain the requested_time structure, customer object, or service field beyond what the schema shows. Still, the description adds meaningful context for the core action parameter.

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 set (lookup, hold, confirm, reschedule, cancel) and a resource (appointments with an SMB), and it distinguishes the tool from siblings by noting it routes through the SMB's native booking system, voice AI, or web form. It clearly covers the action enum and the tool's 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 states when to use the tool (for appointment operations with an SMB) and gives context about routing behavior, but it does not explicitly say when not to use it or name alternatives. Sibling names like check_booking_link and import_booking_url imply related but different use cases, yet the description doesn't explicitly exclude them.

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 safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that each list is fetched from the issuing authority, that alternate spellings come from ALT.CSV, and that the UN list is deliberately omitted due to licensing. It also discloses the quota/pricing model ('free in quota, then $0.02/call'), which is useful cost-awareness 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?

The description is a single dense paragraph that front-loads the core purpose and then adds the key exclusions and pricing. Every sentence earns its place: the list enumeration, the UN exclusion with rationale, and the cost note. It is slightly long but not bloated, and the most decision-relevant information (what is screened and what is not) appears early.

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 main things an agent needs: what lists are searched, what is excluded and why, and the cost model. It does not describe the output format or match scoring, but since there is no output schema and the tool is a simple screening lookup, a brief note on return shape would have made it complete. Still, the coverage is strong for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a little context by mentioning alternate spellings (ALT.CSV), which implies why the 'name' parameter may match variants, but it does not add meaningfully beyond the schema for 'type' or 'country'. Baseline 3 is appropriate because 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 opens with a specific verb ('Free screening') and a precise resource ('a name or entity against official sanctions lists'), then enumerates the exact lists covered (OFAC SDN, EU consolidated, UK FCDO). It also explicitly names what is NOT covered (UN Consolidated List) and why, which sharply distinguishes it from any sibling that might look similar.

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 tool's scope and the data sources, and it explicitly excludes the UN list with a licensing rationale, which helps an agent decide when not to rely on it. It does not name sibling tools or provide explicit 'use this instead when...' guidance, but the context signals show siblings are unrelated (get_outcome, get_status, etc.), so the exclusion of the UN list is the main routing guidance and it is clear.

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?

Beyond the annotations, the description discloses the non-bypassable compliance gate, rejection of non-consented marketing content, synchronous returned message ID with async delivery status, and pricing. This gives the agent a realistic model of the tool's side effects and follow-up 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?

The description is dense but not bloated. It front-loads the core action then adds compliance, async behavior, and pricing in a compact way. The trailing pricing fragment is slightly rough but not confusing.

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 does, legal/compliance constraints, channel support, message categories, async status retrieval via get_outcome, and cost. It omits detailed error modes and per-channel differences, but there is no output schema and the description still gives an agent 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 schema already documents most parameters (idempotency_key, preferred_channel, message_type). The description adds some context around message types and consent, and clarifies the on-behalf-of framing. However, it does not explain content, template fields, or channel-specific constraints 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 clearly names the verb ('send'), the object ('a message'), the supported channels, and the on-behalf-of scope ('an agent's user or an SMB'). It also enumerates the five message types, so an agent immediately knows what the tool does and what categories it accepts.

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 gives actionable usage direction: marketing content requires recorded consent or will be rejected, and it says to track delivery via get_outcome. It does not compare against sibling sending tools, but no sibling tool names were provided to the evaluator, so this cannot be penalized heavily.

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

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

The description claims 'Idempotent transactional messages' and describes a idempotency key with 24-hour replay behavior, while the idempotentHint annotation is false. This is a direct contradiction, so the score is 1 as per rubric. Additionally, the destructiveHint annotation is true, but the description gives no explanation for destructive behavior, further confusing the agent; the contradiction overrides any transparency gains.

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-loads the core purpose, then adds channel fallback, pricing, and async routing in order. The '[async→get_outcome]' and pricing details are useful but slightly dense; the overall structure is efficient and informative without repetition.

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

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

Given the tool's complexity (5 params, nested objects, no output schema), the description fairly well explains behavioral nuances like idempotency and honest channel failure, and points to get_outcome for asynchronous results. What is missing is an explicit statement about return values or error handling beyond the failure claim, but the async mention and channel guarantees cover the most critical operational context.

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

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

The schema description coverage is only 40%, and the description does not compensate for the missing documentation. It loosely maps to the confirmation_type enum by listing transaction categories but offers no detail on how to construct the 'data' object or what 'preferred_channel' values mean, leaving much to inference. The idempotency_key is already well-documented in the schema, so the description adds marginal value there.

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 defines the tool's domain as 'Idempotent transactional messages' and enumerates concrete use cases (OTPs, booking confirmations, payment receipts, cancellation notices), which gives a clear sense of its purpose. However, it does not explicitly contrast itself with the sibling tool send_message, leaving the reader to infer the distinction between transactional and general messaging.

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 states the category of messages it is for (transactional) and includes a concrete async guidance: '[async→get_outcome]', which tells the user next steps. It does not provide explicit 'when not to use' comparisons to siblings, but the transactional scope and async note give adequate context for common invocation decisions.

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.