Odile Labs

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

Goes far beyond destructiveHint=true and idempotentHint=false by naming the real consequences: the answer is spoken on a live call and cannot be taken back, there is a 45-second deadline after which the assistant proceeds without you, and specific content patterns cause outright rejection. It also states the required scope (direct:tasks) and ownership precondition, which no annotation conveys.

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 and the gating condition come first, then consequences, then restrictions — a sensible front-load. It is a dense multi-clause paragraph with some repetition between the prose restriction list and the schema's own wording, which keeps it from a 5.

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?

No output schema exists, yet the description tells the agent exactly what comes back ('the call state') and where to look next (get_call_result). With required scopes, ownership, timing, content limits and an example all covered, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the 300-character practical limit, the 'keep it short and factual' style guidance, the concrete input_required source of answer, and a worked task_id/answer example. Minor residual gap is that it doesn't explain what a task_id looks like structurally beyond the example.

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 ('give the calling assistant your answer to a question the business asked') and ties it to the specific tool that produces the need (call_business). An agent can distinguish it from call_business, reply_to_business, and get_call_result 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?

Explicit gating condition: 'Use it only when get_call_result shows state input_required (its pending_question holds the question)', with the alternative behavior spelled out if the 45-second window lapses. The when-to-use, when-not-to-use, and prerequisite are all present.

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 annotations: the call 'cannot be recalled', requires the direct:tasks scope, developer opt-in, and per-person consent; calls run Mon–Fri 9:00–17:00 local with a next_window error; no number is dialed twice in 24h and accounts have a daily cap. It also states the return shape and routes progress checks to get_call_result, plus credit cost lookup via get_m2m_network.

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 and tool routing, then constraints, then a worked example — all sentences carry information. It is a dense single block, however, and the eligibility/compliance clauses could be grouped more scannably rather than run together.

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-required-parameter destructive action with no output schema, the description covers prerequisites, consent, scheduling, idempotency, return fields, and follow-up tooling. Nothing an agent needs to invoke it safely 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 already 100%, so the baseline is 3; the description adds genuinely new meaning — number and callback_number must be callable US/Canadian E.164, callback_number is the person's own and never the business's, and message_id must be reused unchanged on retries to guarantee a single call. It does not elaborate on optional questions/max_seconds, keeping it just below a 5.

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 ('place an outbound phone call to a business to ask for information on a named person's behalf') and explicitly differentiates from siblings find_business_agent and send_to_business with the exact conditions that select each. An agent can choose correctly 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?

Gives explicit when-to-use ('when find_business_agent returned not_found for a US or Canadian number'), when-not ('when a Direct card exists use send_to_business'), and hard exclusions ('Informational calls only: no sales, payments or account access'). Operating-window behavior and the refusal path are also spelled out.

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 cover read-only/idempotent/openWorld) by disclosing rate limits (30 lookups per IP per hour anonymous, 10000 per key per day signed in), the error payload shape, and that it 'contacts no business.' That is exactly the operational context an agent needs before calling.

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 and the 'start here' routing instruction, then format, then returns, then limits and edge cases — a sensible order. It runs long and packs many clauses into single sentences, but nearly every clause carries actionable information; the trailing example is mildly redundant with the schema.

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

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

There is no output schema, yet the description documents the return object fields ({agent_card, business, trade, town}), the meaning of the /b/ vs /c/ card paths, and the not_found error shape. Nothing an agent needs to call it and consume the result is missing.

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

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

Schema coverage is 100% and the schema already has the E.164 pattern and an example, so the description's format restatement is partly redundant. It does add meaning by explaining the number must be 'as customers dial it' and that any other format is rejected, which clarifies the real-world source of the value.

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

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

States a specific verb+resource: 'Look up a business by its phone number in the Odile Direct directory and get its Direct card.' It also positions itself relative to siblings (send_to_business needs the id from this card; call_business availability via voice_fallback), so an agent can tell what this tool is and is not.

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

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

'Start here' explicitly establishes this as the entry point before send_to_business, and it names the downstream alternative for unlisted US/Canadian numbers via voice_fallback/call_business. It also states a negative case (not on Direct → not_found with claim_url and listings_url), leaving little 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 declare readOnlyHint=true and idempotentHint=true, and the description adds valuable context beyond them: requires direct:tasks scope, ownership enforcement (another account's task_id returns Not found), the full state machine, the return shape including pending_question with expires_at, and confirmation that it changes nothing and starts no call.

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 front-loaded: purpose first, then polling states, auth/ownership, return values, and a short example. Every sentence carries operational value and there is 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?

No output schema exists, but the description fully specifies the return shape ({task_id, state, outcome, duration_seconds, transcript, answers, summary, cost}, plus pending_question). Combined with the state machine and auth notes, an agent has everything needed to call and poll correctly.

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

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

Schema coverage is 100% and already documents that task_id comes from call_business. The description adds a concrete format example (task_id='dv_9a3') and ties the parameter to the ownership/Not found behavior, providing meaningful extra semantics 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?

States a specific verb and resource: read the state and outcome of a business call placed with call_business. It explicitly distinguishes this from get_line_calls (calls your answering line took) and from answer_call_question, so an agent can tell exactly which tool to use.

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 explicit polling guidance: call it again until the state is final, with queued/dialing/in_call as in-progress and completed/no_answer/voicemail/refused/failed as final. It also names answer_call_question as the alternative when input_required appears within the 45-second window.

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 annotations: it names the required scope (direct:tasks), discloses that it 'creates no new charge or booking identity,' warns that a verified paid checkout 'may finish its already-authorized held booking' (explaining why readOnlyHint is false for a get_* tool), cautions that 'paid does not mean a bank payout,' and confirms repeat safety. This is exactly the contextual disclosure annotations cannot carry.

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 verb and purpose, and every sentence carries operational weight. It is on the long side, with mild redundancy about payment_url and the example repeating the trigger condition already stated in the second 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?

No output schema, but the description still tells the agent what comes back (receipt plus separate booking state), what is and isn't knowable (payout status unknown), prerequisites, and side-effect boundaries. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds provenance ('the business id from its card', the task id send_to_business returned) and a concrete example with format hints (biz='harbor-plumbing', task_id='tk_5d0'), though it largely restates the schema's own parameter wording.

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: 'Check an existing deposit booking... reconcile its Stripe Checkout payment and return its receipt and the separate booking state.' It also distinguishes itself from siblings by naming send_to_business as the predecessor and noting that it 'cannot start a payment.'

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

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

Explicit trigger: 'Use it after send_to_business returned a payment_url for a deposit booking.' Explicit exclusion: 'it cannot start a payment, which the person makes on Stripe's hosted page.' The only prerequisite, the direct:tasks scope, is named.

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 context the annotations do not: the direct:tasks OAuth scope and sign-in requirement, the closed scope of the data (only the last 20 charges), and that phone minutes and legacy credits live elsewhere. 'Changes nothing' and 'never buys credit' partly restate readOnly/destructive hints, which keeps it just 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?

Front-loaded with the resource and returned fields, then usage, then prerequisites. Every sentence is relevant, though the parenthetical enumerations and the 'same ledger as REST and your developer page' aside make it denser than strictly necessary.

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-value burden and does so by listing each returned datum plus its unit (cents) and window (last 20 charges). Auth requirements, side-effect profile, and boundary with sibling tools are all covered, so nothing an agent needs 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 takes zero parameters, which is the baseline-4 case. The description reinforces this with an explicit no-argument invocation example, leaving no ambiguity about how to call it.

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 (read) plus exact resource (the signed-in account's Direct ledger) and enumerates the fields returned: UTC free-send allowance, prepaid balance in cents, reserved cents, last 20 charges. It also explicitly distinguishes itself from get_m2m_network (which lists costs) and get_direct_payment, so an agent can route correctly 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?

Gives a concrete trigger ('Use it before sending tasks that may cost credit'), names the follow-up path (a payment_required reply from send_to_business carries the top-up link), and redirects cost lookups to get_m2m_network. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds non-obvious context: reference data, nothing account-specific, needs no sign-in, contacts no business, and that it is safe to call once per session rather than repeatedly. It stops short of describing freshness/staleness of the pricing card, which would be the remaining behavioral unknown.

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 purpose and the contents of the card, with the sibling exclusions and the trigger example at the end where they belong. Slightly dense — the long enumerated return list plus the 'changes nothing' restatement of destructiveHint could be trimmed — but nearly 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?

There is no output schema, so the description compensates by naming the returned fields (pricing card, live_skills shape, mcp_url, gate_mcp_url, quickstart_url, docs_url, connect_steps). Combined with the auth/side-effect disclosure and the call-timing example, an agent has everything needed 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?

Zero parameters, so the baseline is a 4, and the description confirms it explicitly with 'takes no arguments', removing any doubt about whether filters or identifiers are required. No further parameter meaning is possible.

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: 'Read the OdileM2M network card for Direct,' followed by an enumeration of exactly what the card contains (live skills, credit costs, packs, limits, Gate MCP address, quickstart). It explicitly positions itself against two named siblings, so an agent can distinguish it 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?

States the use case ('cost Direct tasks before sending any'), the exclusions with named alternatives (get_agent_services for product choice, get_direct_usage for own balance), and a concrete trigger ('call it once with no arguments before the first send_to_business of a session'). Nothing 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 declare read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them: it does not wait, unknown thread or bad token returns not_found, threads expire 90 days after last message, and it uses no credits. It also describes the return structure in detail.

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 and usage, and most sentences earn their place. The dense return-value enumeration makes it longer than necessary, but the detail is useful and well organized.

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 no output schema and a simple two-parameter read operation, the description covers usage, authentication, failure modes, expiration, and the exact return shape. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces where thread_id comes from and the thread_token fallback, plus an example, but adds little semantic information beyond the schema text.

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: read replies in a Direct conversation started with send_to_business, including status and messages. It clearly distinguishes itself from sibling tools by naming get_line_messages and get_call_result as out of 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?

Explicitly says when to use it (to find out whether the business has answered), notes that it does not wait and should be called again later, and names alternatives for related but different needs. It also specifies the required thread_id and authentication options.

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 destructiveHint=true and idempotentHint=true; the description goes further by saying the reply cannot be recalled, is billed like a take_message task, that closed conversations refuse it, and that message_id is the retry key to reuse unchanged. It also tells the agent to read the returned {task} state before claiming delivery, which is valuable behavioral context. Only gap: it doesn't say what happens on partial failure or how billing/side effects interact with a retried message_id, so it's strong-but-not-exhaustive rather than a full 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-loaded purpose, then routing, then parameters, then a worked example — every part earns its place. The parameter sentence is dense (thread_id, text length, auth, retry key in one breath) and could be split for readability.

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 return value (A2A {task}) and warning to read its state before asserting delivery. Combined with auth, billing, and closed-conversation constraints, an agent has what it needs; only failure-mode details are thin.

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 all four parameters are already documented; the description corroborates thread_id provenance (from send_to_business) and reinforces message_id as a retry key. It adds the auth choice (sign in as requester with direct:tasks, or supply thread_token) which is meaningfully beyond the schema text.

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 ('Send a customer reply in an open Direct conversation') and immediately distinguishes itself from send_to_business (new conversation) and answer_call_question (live phone call). An agent can route correctly 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?

Gives an explicit trigger ('after get_replies shows the business answered'), names two alternatives with the conditions that select them, and adds a prerequisite-style constraint that closed conversations refuse replies.

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 (destructiveHint=true, idempotentHint=false, openWorldHint=true): it discloses that a delivered message cannot be recalled, that a booking is only undone via cancel_booking, that message_id makes the request run once (and the same-UTC-day fallback when omitted), that deposit bookings are held 30 minutes pending payment, and which outcomes are not charged. It also explains the return contract as an A2A task whose state must be read before reporting success.

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 the skill list, then prerequisites, then invariants, then return behavior, so an agent can stop reading early. It is a dense single paragraph for a genuinely complex tool, but some clauses (costs, balance lookups) could be pulled into a reference rather than the main description.

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

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

With no output schema and six parameters including a free-form nested data object, the description still covers the async A2A task envelope, the INPUT_REQUIRED/payment_url deposit case, thread_id/thread_token reuse, and which failure states incur no charge. Nothing an agent needs to interpret the result or retry safely is missing.

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

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

Schema coverage is 100%, so the schema already carries field-level meaning and the baseline would be 3; the description adds value by explaining message_id as the retry key across the whole request and by supplying a worked example that shows how biz, skill and the nested data fields compose. The approval_id flow and the anonymous-vs-signed-in callback_number distinction are reinforced rather than duplicated verbatim.

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 ('Send one request to a business') and immediately enumerates the five skills (take_message, check_availability, book, book_first_available, cancel_booking) that define what the request can be. This distinguishes it from call_business and reply_to_business, which it explicitly routes to for different situations.

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 explicit ordering ('Call find_business_agent first'), a named fallback ('for a business without a card, use call_business'), and a routing rule after success ('use get_replies ... and reply_to_business'). It also states a precondition ('get the person's permission before booking') and a required disclosure ('Say an automated assistant is acting').

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