Remote MCP for three phone actions: call_me calls your verified number for decisions, call_person relays a user-approved message to a specified person, and call_business calls businesses for inquiries or bookings. Results return to the agent. Each user supplies a LifeClaw Bearer API key; outbound calls may use account credits. Setup: https://lifeclaw.agentese.ai/mcp
Scored across 16 tools
The four call tools (call_business, call_contact, call_person, call_me) and three status tools (account_status, caller_id_status, receiving_phone_status) could easily blur together, but the descriptions explicitly cross-reference and delineate each one (e.g. saved contact vs raw number, outbound vs receiving setup). call_contact is effectively a convenience wrapper over call_person, a mild overlap, but overall selection is clear.
Nearly all tools follow a snake_case verb_noun pattern (call_business, list_contacts, save_contact, search_places, wait_for_call). The three status tools (account_status, caller_id_status, receiving_phone_status) deviate by omitting a verb, though they are internally consistent with each other.
16 tools is slightly on the heavy side but each maps to a distinct domain capability: calling, contacts CRUD, place lookup, bookings, accounts/status, and async polling. Nothing feels redundant or gratuitous.
Coverage is strong: contacts have full CRUD, places have search+details, and bookings have list/modify with creation handled via call_business, plus wait_for_call for async results. Minor gaps remain — no standalone booking-creation or task-status-by-id tool — but the core lifecycle is closed.
Points balance, display name, and the selected receiving number for call_me (masked). Use receiving_phone_status for setup and caller_id_status for outbound display and outbound-display state. 300 points ≈ one minute of calling.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe, read-only, closed-world operation, so the bar is low. The description still adds genuine value beyond them: the receiving number is returned masked, and 300 points converts to roughly one minute of calling, which tells the agent how to interpret the balance without a follow-up 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?
Three short sentences with no filler, front-loaded on the returned fields before the sibling routing. The first sentence is a bare noun-phrase list with awkward line wrapping, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description is not obliged to document return values, yet it still names the key fields and their units. Combined with the sibling cross-references, an agent has everything needed to select and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level guidance is needed or missing.
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 enumerates exactly what the tool surfaces: points balance, display name, and the selected masked receiving number for call_me. The verb comes from the title ("Check account status") rather than the body, but the resource set is specific enough to distinguish it from siblings like caller_id_status and receiving_phone_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes the agent to receiving_phone_status for setup and caller_id_status for outbound display state, which are concrete alternative-selection rules. It stops short of stating the primary when-to-use condition (checking balance/account identity) in so many words, leaving that to inference from the listed return values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Phone a business and wait for the outcome.
action="book": reserve. Required: merchant_name, date (YYYY-MM-DD),
time_ (HH:MM, 24h), party_size, name; recommended: contact_phone (E.164).
Both are the MERCHANT's local time.
action="inquiry": ask something — put the question in purpose; the
answer comes back in result.summary.
reply_language is the language of the result fields (the call itself
is spoken in the merchant's language). idempotency_key: reuse the same
key to recover this attempt; after a terminal no-answer or busy result,
a deliberate new call needs a new key. Do not redial a failed result:
its cause may be unknown. Without a key, the same arguments derive the
same key for the UTC day and return the original task.
For personal accounts, a verified and enabled Caller ID is shown to the business when the route permits it. Otherwise a LifeClaw number is used. Caller ID setup is optional for business calls.
Returns the flat result (result.status is confirmed / rejected /
pending / no_answer / busy / unclear / timeout / failed, plus summary,
details, conditions, transcript) or status: in_progress with a task_id
for wait_for_call.
Costs 300 points per minute, minimum one minute, nothing on no answer.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Requested date in YYYY-MM-DD, merchant local time. | |
| name | No | Name under which to make the booking. | |
| time_ | No | Requested time in HH:MM, merchant local time. | |
| action | No | Call action, such as book or inquiry. | book |
| purpose | Yes | What to ask or arrange during the call. | |
| phone_ref | Yes | Signed phone reference from get_place; never invent one. | |
| party_size | No | Number of people for a booking. | |
| predicted_qa | No | Likely questions and user-approved answers. | |
| wait_seconds | No | Seconds to wait for the call result before returning a task ID. | |
| contact_phone | No | Customer contact number in E.164 format. | |
| merchant_name | No | Business name for the booking or inquiry. | |
| reply_language | No | Language for the returned result, such as en or zh. | en |
| idempotency_key | No | Stable event key to prevent a retry from placing a second call. | |
| special_requests | No | Additional requests to tell the business. | |
| fallback_instructions | No | What to do if the requested option is unavailable. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already flagging openWorld/destructive, the description adds substantial non-obvious behavior: idempotency_key reuse/dedup rules, the day-scoped derived key, caller-ID routing, terminal result statuses, cost of 300 points/minute with a one-minute minimum and no charge on no-answer. That is exactly the kind of real-world side-effect detail the annotation cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but deliberately organized: lead sentence, then per-action blocks, then cross-cutting notes on language/idempotency/caller ID/return/cost. Every sentence carries operational weight given a 15-parameter, side-effecting tool; only minor tightening is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, non-reversible, costly tool the description covers the full calling contract: required inputs per mode, time formats, idempotency, terminal vs in_progress outcomes, handoff to wait_for_call, and billing. An output schema exists, so enumerating result fields in more depth is unnecessary.
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 goes further by grouping which parameters are required per action, pinning date/time to merchant local time, and explaining reply_language vs the spoken language and the idempotency_key semantics. It leaves predicted_qa, wait_seconds, special_requests, fallback_instructions and phone_ref to the schema, so it is not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb+resource ('Phone a business and wait for the outcome') and the action-mode breakdown makes the two distinct operational shapes (book vs inquiry) explicit. An agent can separate this from call_person/call_contact/call_me on the 'business' target 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?
Clearly states when to use each action and routes the agent to wait_for_call for in_progress results, plus gives a do-not-redial rule for failed results. It stops short of an explicit 'use call_person instead when...' sibling contrast, so it lands just under full marks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call a saved private contact without passing their full number.
First list_contacts and confirm the chosen name, masked number and exact spoken message with the user. Pass that contact_ref and user_confirmed=true. If the contact changes before dialing, re-list and confirm again. This uses call_person's screening, verified Caller ID, daily cap and strict no-platform-number-fallback policy. Check caller_id_status first. Its no-answer retry decision and idempotency rules are the same as call_person.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The exact message the AI will say on the phone. | |
| language | No | Language the AI should speak during the phone call. | |
| contact_ref | Yes | Opaque reference from list_contacts for that contact. | |
| contact_name | Yes | Exact name from list_contacts confirmed by the user. | |
| wait_seconds | No | Seconds to wait for the call result before returning a task ID. | |
| reply_language | No | Language for the returned result, such as en or zh. | en |
| user_confirmed | Yes | True only after the user explicitly confirms the recipient and action. | |
| idempotency_key | No | Stable event key to prevent a retry from placing a second call. | |
| original_message | Yes | The user's original, unedited request for content screening. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing inherited behavior from call_person: content screening, verified Caller ID, a daily cap, a strict no-platform-number-fallback policy, no-answer retry decisions, and idempotency rules. It does not spell out what 'destructiveHint' means for this specific action (e.g. whether a placed call can be cancelled), so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the constraint, then the required sequence, with every sentence carrying a distinct instruction. The closing references to call_person's retry and idempotency rules are slightly indirect but still useful and compact.
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 nine-parameter, externally-effecting call tool with an output schema, the description covers prerequisites, confirmation gating, safety policies, and retry/idempotency inheritance. Nothing essential to invoking it correctly is missing, and return values are legitimately left to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all nine parameters are already documented, and the description mainly restates the contact_ref/user_confirmed relationship the schema carries. The added nuance (re-list and re-confirm if the contact changed before dialing) is really workflow guidance rather than parameter meaning, so the baseline 3 fits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource ('Call a saved private contact') and immediately carves out scope versus the number-based sibling with 'without passing their full number.' An agent can distinguish it from call_person and call_business 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 ordered workflow (list_contacts first, confirm name/masked number/message, then pass contact_ref and user_confirmed=true), a pre-flight check (caller_id_status), and a re-confirmation condition if the contact changes. Alternatives and prerequisites are named rather than implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the owner's outbound Caller ID. Verified plus enabled display
enables call_person. call_me uses a separate receiving number.
If setup is needed, direct the user to setup_url: Settings → Caller ID,
bind their own phone, answer Twilio's verification call and enter its code.
Then check again. Business calls do not need this setup.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare safety flags (destructive=false, openWorld=false); the description carries the real behavioral burden and does so well: what the status gates, that call_me is unaffected, and the out-of-band Twilio verification workflow. It does not reconcile the unusual readOnlyHint=false for a 'check'-style tool, which leaves a small ambiguity about whether calling it triggers any remote action.
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, then gating semantics, then the remediation steps — each clause carries information. It is slightly dense with mixed audience content (agent logic plus user-facing UI instructions), and the line-wrapping fragments the flow, but nothing is 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?
An output schema exists, so return-value detail is not required, and the description covers prerequisites, the downstream effect on call_person, the setup escape hatch, and the business-call exception. The remaining gap is the absence of any cross-reference to receiving_phone_status and the unexplained readOnlyHint=false.
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, so the baseline is 4. The description correctly adds no parameter noise, and the only implied input (the account context) is implicit rather than schema-driven.
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 ('Check the owner's outbound Caller ID') and immediately differentiates itself from call_person (gated by this status) and call_me (uses a separate receiving number). An agent can place this tool in the call flow without opening any other 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 gating logic ('Verified plus enabled display enables call_person'), a remediation path when setup is missing (direct user to setup_url with the exact steps), and an exclusion ('Business calls do not need this setup'). It does not, however, compare itself to the sibling receiving_phone_status, which is the obvious adjacent lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ring the user's own phone, read them message, and bring back what
they say.
A phone call interrupts the user. Follow their explicit instructions about
whether and when to call, including an immediate call or a call when a job
finishes. Otherwise prefer chat for routine updates; call for a time-sensitive
decision only they can make after chat has no explicit answer, or for a
still-active important event after the workflow's chosen wait if nobody has
acknowledged it. There is no fixed waiting period: use the user's timing
when given, otherwise choose one appropriate to the task. For monitoring,
your workflow must watch the event, wait for acknowledgment, and decide
when to invoke this tool; LifeClaw cannot do those things or schedule a
future call. An explicit request to call regardless of event status takes
priority over the default active-and-unacknowledged condition.
Consider local time and do not repeatedly ring after a missed call. A
terminal no-answer is for your workflow to assess; LifeClaw will not
redial it automatically. Do not redial a failed result because contact
may have occurred. A deliberate later call needs a new
idempotency_key, and only a workflow that can wait and resume can promise
one. Reuse the original key to recover an uncertain request instead.
Examples: (1) a deployment is blocked on a rollback decision and chat
has no explicit answer; ask that one question and use result.reply.
(2) An external monitor confirms a critical incident is still active
and unacknowledged; call with that incident ID as idempotency_key.
(3) The user asked for a call when a job finishes; call once when your
workflow observes completion. Do not call for an ordinary completion
the user did not ask to hear by phone.
wait_for_reply=True: the assistant asks, listens, reads the answer
back, and returns it in result.reply. wait_for_reply=False: deliver
and hang up. agent_name ("Claude Code", "Codex") is how the assistant
introduces itself. language is spoken on the call and used for the
result; set it to the user's language. Write the message as speech:
short sentences, no markdown. Do NOT greet or introduce yourself inside
message — the call already opens with "I'm your assistant from
{agent_name}" / "我是来自 {agent_name} 的 AI 助手"; a message that starts
with "Hi, this is Claude Code" gets introduced twice. Start with the
content ("Hotpot or sushi tonight?").
keywords (optional, up to 20 short terms): the words the user is likely
to say back — the options you offered ("火锅", "日料"), a ticket or PR
number, a product name. They steer the speech-to-text toward those
spellings so result.reply and the transcript come back right; phone
audio otherwise mishears short words (火锅 → 哥哥 on a real call). Give
them whenever the answer is a choice between named things.
Needs the account's voice-verified receiving number. Outbound Caller ID
is separate. If this returns error: receiving_phone_required, send the
user to the returned setup_url to select a number, answer the voice
verification call, and enter its code.
Capped at 4 calls per account per 10 minutes and 30 per 24 hours. Billed
per minute like any call. For monitoring, pass a stable event ID as
idempotency_key; a new event needs a new key.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Short message or decision question to read to the account owner. | |
| keywords | No | Terms the speech recognizer should expect. | |
| language | No | Language the AI should speak during the phone call. | en |
| agent_name | No | Agent name used to introduce the call. | |
| wait_seconds | No | Seconds to wait for the call result before returning a task ID. | |
| wait_for_reply | No | Whether to listen for and return the owner's answer. | |
| idempotency_key | No | Stable event key to prevent a retry from placing a second call. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give the generic readOnly=false/destructive=true/openWorld=true profile; the description supplies the specifics that actually matter — 4 calls/10 min and 30/24 h caps, per-minute billing, no automatic redial, no scheduling, the `receiving_phone_required` error and its setup_url recovery flow, and idempotency semantics for monitoring. This is well beyond what the annotations convey and consistent with them.
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, then routing policy, then examples, then per-parameter guidance — a sensible order with no filler sentences. It is long and revisits idempotency_key/redial rules in two places, which costs a point, but the length is largely justified by the tool's real complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, high-stakes, open-world call tool this covers everything: prerequisites (voice-verified receiving number), failure recovery path, rate limits, billing, idempotency, redial policy, and how to read `result.reply`. An output schema exists, so return-value documentation is appropriately referenced rather than duplicated.
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 terse schema fields lack: what wait_for_reply does in each mode, how agent_name is spoken in the greeting, that language drives both speech and the result, why keywords steer speech-to-text (火锅 → 哥哥), and what idempotency_key does on retry/uncertainty. It also carries the non-obvious "do not greet inside `message`" constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line states a concrete verb+resource+scope: ring the user's own phone, read them `message`, return what they say. The phrase "the user's own phone" implicitly separates it from the sibling tools that call other people (call_person, call_contact, call_business), so an agent can route without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use vs when-not: prefer chat for routine updates, call only for a time-sensitive decision chat could not resolve or a still-active unacknowledged event after the chosen wait. It also covers timing policy, monitoring responsibilities, priority of explicit user requests, missed-call handling, and redial prohibitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call one private person and relay one message from the user.
Ask the user to confirm the recipient, E.164 number and exact spoken
message first, then set user_confirmed=true. original_message is the
user's unedited request; message is the faithful sentence spoken aloud.
Both are screened. The AI identifies itself and passes on the message;
this tool is not an open-ended conversation or a broadcast tool.
Requires the user's verified, enabled outbound Caller ID. Call
caller_id_status for readiness and setup link. Verification means answering
a call and entering a code; call_me uses a separately selected receiving number.
Never substitute call_business for a private recipient. If the Caller ID
is refused by the carrier, the call fails without a platform-number retry.
Up to 10 private calls per account per rolling 24h. Billed per minute.
Reuse the same idempotency_key to recover this attempt; wait_for_call if
in_progress. Only after a terminal no-answer or busy result with no contact
should your workflow consider another call, using a new key and respecting
the user's instructions and the recipient's local time. Do not redial a
failed result because it does not establish that nobody was reached.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The exact message the AI will say on the phone. | |
| language | No | Language the AI should speak during the phone call. | |
| phone_number | Yes | Confirmed recipient number in E.164 format. | |
| wait_seconds | No | Seconds to wait for the call result before returning a task ID. | |
| recipient_name | Yes | Confirmed name of the person to call. | |
| reply_language | No | Language for the returned result, such as en or zh. | en |
| user_confirmed | Yes | True only after the user explicitly confirms the recipient and action. | |
| idempotency_key | No | Stable event key to prevent a retry from placing a second call. | |
| original_message | Yes | The user's original, unedited request for content screening. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing rate limits (10 private calls per rolling 24h), per-minute billing, the verified/enabled Caller ID prerequisite, carrier-refusal failure behavior with no platform-number retry, idempotency-key reuse, and the redial policy distinguishing terminal no-answer/busy from a failed result.
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 confirmation prerequisite, then arranged by prerequisite, alternatives, failure mode, limits, and retry policy. Dense but each clause carries operational weight; the verification/caller_id_status aside and the redial paragraph are slightly longer than strictly needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, billed, outbound-calling tool with 9 parameters, it covers the confirmation gate, auth prerequisites, rate limits, idempotency, retry semantics, and sibling routing. Return values need not be described since an output schema exists and wait_seconds/wait_for_call behavior is addressed.
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 semantic distinctions the schema does not: original_message is the user's unedited request while message is the faithful sentence spoken aloud, both screened; and idempotency_key must be reused to recover the same attempt rather than place a second call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: "Call one private person and relay one message from the user." It explicitly bounds scope ("not an open-ended conversation or a broadcast tool") and names the sibling it must not be substituted for ("Never substitute call_business for a private recipient"), so the agent can route between call_person, call_business, and call_me without opening schemas.
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 preconditions (confirm recipient, E.164 number, exact spoken message, then set user_confirmed=true), names alternatives with selecting conditions (caller_id_status for readiness, call_me for a receiving number, wait_for_call for in_progress), and defines when a retry is and is not permitted. 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.
Delete a saved contact by exact name after the user confirms deletion.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact saved contact name to delete. | |
| user_confirmed | Yes | True only after the user explicitly confirms the recipient and action. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered there. The description adds the confirmation gate, but that requirement is also encoded in the required user_confirmed parameter, so the marginal context is thin – no statement on irreversibility or error behavior for a non-matching name.
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, front-loaded with the action, and every clause carries information: what is deleted, how it is identified, and the gating condition.
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 two-parameter destructive tool with annotations covering safety and an output schema covering the return value, the description supplies the action and the confirmation gate, which is enough to call it correctly. Missing only edge-case guidance such as behavior when no exact match exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented there, including the exact-match semantics of name and the meaning of user_confirmed. The description's 'exact name' phrasing restates the schema rather than extending it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (a saved contact) plus the lookup key (exact name), which cleanly separates it from save_contact, update_contact, and the call_* siblings. An agent can select it without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the key precondition – deletion only happens after the user confirms – which is the main thing an agent needs to know before invoking. It stops short of naming alternatives or when-not-to-use cases (e.g., what to do if the name is not an exact match).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full details for one place from search_places: phone, hours, rating,
website, booking link. Pass the same location you searched with.
phone_ref is the handle call_business needs; when it is null the place
cannot be called and phone_ref_unavailable_reason says why — show the
user detail.phone / detail.booking_url instead. Costs 15 points.
| Name | Required | Description | Default |
|---|---|---|---|
| cid | Yes | Place identifier returned by search_places. | |
| name | Yes | Business name from search_places. | |
| language | No | Language for business details. | en |
| location | No | The same search location used for search_places. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations give readOnlyHint=false, destructiveHint=false, openWorldHint=true, and the description supplies the missing context: the call costs 15 points, explaining the non-read-only flag. It also discloses the phone_ref null case, the phone_ref_unavailable_reason field, and the field fallbacks to show the user, none of which the annotations reveal.
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 returned fields are front-loaded in the first sentence, followed by the location convention, the phone_ref/call_business relationship, and the cost. Every sentence carries unique information and none is redundant.
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 4-parameter lookup tool with an output schema and partial annotations, the description covers everything an agent needs to invoke and route correctly: the location convention, the cost, the phone_ref handoff to call_business, and the null-case fallback. Return-value explanation is unnecessary given the output schema, yet the phone_ref semantics still add value.
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 cid, name, language, and location. The description reinforces the location constraint and adds the same-location convention, but that repeats what the schema property description already states, so it adds little beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Full details for one place') and enumerates the returned fields (phone, hours, rating, website, booking link). It explicitly positions itself as the follow-up to search_places, so an agent can distinguish it from that sibling without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly implies the sequencing ('one place from search_places', 'Pass the same `location` you searched with') and routes the agent to call_business via the phone_ref handle, with an explicit fallback when phone_ref is null. It stops short of an explicit 'use this only after search_places' statement and names no when-not condition, so it is strong context rather than a full decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's bookings (confirmed, cancelled, answered inquiries).
status filters: "confirmed", "cancelled", "answered", or "" for all.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of bookings to return. | |
| status | No | Filter: confirmed, cancelled, answered, or empty for all. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds genuine scope context by disclosing that cancelled and answered inquiries are included, but says nothing about ordering, pagination, or what happens when the limit truncates results.
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 short sentences with no filler, and the resource scope leads before the filter detail. The noun-phrase opening is slightly telegraphic, but nothing is redundant.
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?
An output schema exists, so return values need no explanation, and annotations carry the safety profile. With 100% parameter coverage and an explicit status enumeration, the only unstated detail is result ordering, which is minor for a filtered list.
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 both limit and status are already documented. The description restates the status values ("confirmed", "cancelled", "answered", "" for all) but adds no meaning beyond the schema's identical enumeration. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (the account's bookings) and its scope (confirmed, cancelled, answered), and the title supplies the verb 'List'. An agent can identify what it retrieves, though it never contrasts itself with the sibling modify_booking or list_contacts.
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?
Usage is implied rather than stated: listing bookings for the account, optionally narrowed by status. There is no explicit when-to-use, no exclusions, and no pointer to alternatives such as modify_booking for changes or list_contacts for a different resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the token owner's saved contacts with masked phone numbers.
Each contact_ref pins the current name and number for call_contact. If two names could match a request, ask the user to choose one exact name. Never repeat a full contact number in chat.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/destructiveHint=false, but the description adds non-obvious behavior: numbers come back masked, contact_ref pins the current name-and-number mapping, and full numbers must never be echoed in chat. These privacy and snapshot semantics go beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads what the tool returns in the first clause, then layers the contact_ref contract, ambiguity rule, and privacy rule in tight sentences. No filler; every sentence constrains agent 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?
With zero parameters, read-only annotations, and an output schema present, the description covers the remaining gaps: masking, the contact_ref handle, ambiguity handling, and chat privacy. Little more is needed for an agent to call it and use the result 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 tool takes zero parameters, so the baseline applies; there is no parameter surface for the description to clarify. The mention of contact_ref pertains to the output/returned handle rather than an argument, which is appropriate given the output schema exists.
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 ('List the token owner's saved contacts') and adds a meaningful qualifier ('with masked phone numbers') that tells the agent what kind of data comes back. It does not explicitly distinguish itself from save_contact/update_contact/delete_contact, but the read-only listing intent is 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?
Provides actionable context: contact_ref values feed call_contact, and ambiguous name matches should be resolved by asking the user for one exact name. That is real when/how guidance. It stops short of naming an alternative tool or an explicit when-not condition, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Phone the venue to cancel or reschedule a confirmed booking from
list_bookings. action is "cancel" or "reschedule"; reschedule needs
new_date and/or new_time (merchant local). When the venue confirms, the
booking record is updated for you. Same waiting and idempotency rules as
call_business.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Either cancel or reschedule. | |
| purpose | Yes | What change to request from the business. | |
| new_date | No | New date in YYYY-MM-DD, merchant local time. | |
| new_time | No | New time in HH:MM, merchant local time. | |
| booking_id | Yes | Booking ID from list_bookings. | |
| wait_seconds | No | Seconds to wait for the call result before returning a task ID. | |
| reply_language | No | Language for the returned result, such as en or zh. | en |
| idempotency_key | No | Stable event key to prevent a retry from placing a second call. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is partly covered. The description adds materially: this is an outbound phone call the agent makes on the user's behalf, the booking record is updated only after the venue confirms, and the same waiting/idempotency rules as call_business apply. That is genuine behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then constraints, then the deferral to call_business. Every sentence carries information. It is dense to the point of terseness, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need not be explained. The description covers action semantics, the reschedule prerequisite, confirmation behavior, and idempotency/waiting expectations, which is sufficient for an 8-parameter open-world call tool. Only minor gaps remain, such as explicit failure handling when the venue declines.
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 still adds value the schema cannot express: it ties action to its two values, states that the reschedule fields are conditionally required, and clarifies the merchant-local time basis. The conditional requirement is not encoded as an if/then in the schema, so this is real added meaning.
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 — phone the venue to cancel or reschedule a booking — and anchors it to a sibling artifact ('a confirmed booking from list_bookings'). An agent can distinguish it from list_bookings and call_business 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 clear triggering context (modify a confirmed booking located via list_bookings) and the conditional dependency that reschedule requires new_date and/or new_time. It also defers waiting/idempotency behavior to call_business, an explicit sibling reference. It stops short of saying when not to use it (e.g., creating a new booking belongs elsewhere).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check where call_me would ring (masked). A number must be explicitly selected and verified by voice; SMS login alone does not qualify. The user can set it in the web app without enabling outbound Caller ID. Direct them to setup_url if no receiving number is ready.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false), but the description adds genuinely non-derived operational context: the value is masked, and a voice-verified number is required rather than SMS-only login. It does not describe failure modes when no number is set beyond pointing at setup_url, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each carrying a distinct load: what is checked, what counts as verified, how the user configures it, and where to send them if it is missing. The purpose is front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation, and the description covers the remaining agent-relevant concerns: prerequisite verification, masking, and the remediation path. Nothing needed to act on 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?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No parameter-level confusion is possible here.
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 — checking where call_me would ring — and ties it to the sibling tool call_me rather than describing a generic status check. It also implicitly separates itself from caller_id_status by noting the receiving number is distinct from outbound Caller ID.
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 states the prerequisite (a number must be explicitly selected and verified by voice, and SMS login alone does not qualify), the interaction context (user can set it in the web app), and the fallback action (direct them to setup_url when no receiving number is ready). This is close to a complete when-to-use/when-not guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or update one contact after confirming name and number with the user.
phone_number must be E.164, e.g. +85291234567. This updates the same address book used by the web app. The result masks the number; do not echo the full number in a chat reply. Set user_confirmed only after agreement.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name to save for this contact. | |
| phone_number | Yes | Contact phone number in E.164 format. | |
| user_confirmed | Yes | True only after the user explicitly confirms the recipient and action. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare this is a non-read-only, destructive, closed-world write. The description goes well beyond that: it discloses that the write lands in the same address book used by the web app (cross-surface side effect), that the result masks the phone number, and that the agent must not echo the full number in chat (a privacy constraint on downstream behavior). That is exactly the kind of context 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?
Four short sentences, purpose front-loaded, then format constraint, cross-surface note, and output privacy rule. No filler, though the phone-format sentence and the schema's own E.164 description are somewhat redundant.
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?
An output schema exists, so return-value explanation is not required, and the confirmation workflow plus privacy behavior are covered. It leaves one gap for a destructive write: what happens when the contact already exists (overwrite vs duplicate), which matters given destructiveHint=true.
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 a concrete E.164 example (+85291234567) and reinforces the ordering semantics of `user_confirmed` ('Set user_confirmed only after agreement'), which is slightly richer than the schema's own wording, though it partly restates 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?
Clear specific verb+resource: 'Add or update one contact.' An agent immediately knows this writes to an address book. However it never distinguishes itself from the sibling `update_contact` (or `delete_contact`), which is a real ambiguity for a save/update tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one strong usage rule — confirm name and number with the user first, and set `user_confirmed` only after agreement — which is genuine when-to-use guidance. But there is no routing guidance against the overlapping `update_contact` sibling, so the agent is left to infer which of the two to call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search businesses (restaurants, salons, clinics, hotels…) by free text.
location is REQUIRED and decides which country is searched — a city or
country name ("Tokyo", "Singapore"). Returns up to limit places with a
cid to pass to get_place. Costs 5 points.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of places, from 1 to 20. | |
| query | Yes | Business type or name to search for. | |
| language | No | Language of search results, such as en or zh. | en |
| location | Yes | City or country that determines where the search runs. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds genuinely non-redundant behavior: the query costs 5 points and the hard requirement that location drive the search scope. It does not contradict the annotations, though it never explains why a search is flagged non-read-only, which would have resolved that ambiguity.
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 short sentences, front-loaded with purpose, then the hard constraint, then the return/cost facts. No filler and nothing buried at the end.
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?
An output schema exists, so return values need not be spelled out, yet the description usefully highlights the cid handoff to get_place and the 5-point cost. The only gap is that it gives no sense of result quality or failure modes (e.g. what happens with an unknown location), which for an open-world external search would be worth one clause.
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 query, location, language and limit are already documented with defaults and ranges. The description reinforces that location is required and is a city or country name, which largely restates the schema field text rather than adding syntax or format rules. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Search businesses") and broadens it with concrete examples (restaurants, salons, clinics, hotels) so the agent knows it is a general place lookup, not a business-type-specific tool. It also positions itself in the workflow by naming the downstream sibling get_place, which no other sibling tool claims.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear usage context: location is REQUIRED and determines which country is searched, and results carry a cid to hand to get_place. That is a real routing hint. It lacks an explicit when-not clause (e.g. "use call_business if you already have a cid"), so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a saved contact's name and/or E.164 phone number atomically.
Confirm the existing contact and proposed change with the user first. A name conflict refuses instead of overwriting another person. Return values mask the number; do not repeat a full number in chat.
| Name | Required | Description | Default |
|---|---|---|---|
| new_name | Yes | New contact name. | |
| old_name | Yes | Exact current contact name. | |
| phone_number | Yes | New phone number in E.164 format. | |
| user_confirmed | Yes | True only after the user explicitly confirms the recipient and action. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description earns credit for going further with refusal semantics on name conflict (refuses rather than overwriting) and the privacy rule that return values mask the number and must not be repeated in chat. It does not cover failure modes beyond name conflicts or any permission requirements.
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?
Four short sentences, front-loaded with the action and scope, then the confirmation prerequisite, then the failure and privacy rules. Every sentence carries a distinct and useful constraint with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive 4-parameter mutation with full schema coverage, full annotations, and an output schema, the description supplies exactly the missing pieces: confirmation gating, atomicity, conflict refusal, and output masking. Nothing an agent needs in order to call it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every property carries its own description, so the baseline is 3. The description reinforces the E.164 format and atomicity but adds no syntax, constraint, or interaction detail beyond what the schema already documents.
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 ('Edit a saved contact's name and/or E.164 phone number') with the atomic scope qualifier, which is more precise than the title. It does not name or differentiate against the obvious siblings save_contact and delete_contact, so the agent must infer the boundary itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear prerequisite sequence: confirm the existing contact and the proposed change with the user before invoking. It stops short of stating when to prefer this over save_contact (create) or delete_contact (remove), so alternatives are left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keep waiting for a call that call_business / modify_booking / call_person / call_me reported as in_progress. Returns the flat result once the call ends, or in_progress again — just call it again.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | Task ID returned by a phone tool. | |
| wait_seconds | No | Seconds to wait for the call result before returning a task ID. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/safe and non-open-world, so the description's job is to add semantics: it does, disclosing the long-poll pattern, the two possible return states, and the required re-invocation loop. It does not state what happens if the call never ends or whether repeated polling has cost/rate implications, leaving one behavioral gap.
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 short sentences, front-loaded with the trigger condition, then the return/retry contract. No filler and nothing repeated from 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?
With an output schema present, return values need not be detailed, and the description still usefully summarizes the two outcomes. The main omission is timeout/never-terminating behavior and any guidance on polling cadence beyond "call it again".
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 both parameters (task_id, wait_seconds with default 55) are documented in the schema itself. The description adds no syntax, format, or tuning guidance beyond pointing at task_id implicitly, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (keep waiting/poll for a call result) and ties it directly to the sibling tools that produce the prerequisite state (call_business, modify_booking, call_person, call_me). An agent can immediately tell this is the follow-up/polling tool rather than a call initiator, and the two possible return states are named.
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 clearly states the trigger condition (a call reported as in_progress by one of four named tools) and the retry protocol ("just call it again"). It does not explicitly say when NOT to use it — e.g. that it must not be called before a task id exists — but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
account_statuscall_businesscall_contactcall_mecall_personcaller_id_statusdelete_contactget_placelist_bookingslist_contactsmodify_bookingreceiving_phone_statussave_contactsearch_placesupdate_contactwait_for_call
Add one secure layer between your agents and this server.