Call Me

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

Despite annotations carrying the safety profile (openWorldHint, destructiveHint), the description adds substantial behavioral context beyond them: the ~30s wait, the ringing/in_call/setup_required return statuses, the requirement to read `to` from ~/.aiphone/config.json, the 'Call Me app number, not a regular phone number' constraint, and the default conversation mode with an open line until `hang_up`. None of this is recoverable from the annotations.

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

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

The core action is front-loaded and no sentence is filler — every clause carries a distinct operational fact. It is dense and slightly run-on (a laptop-vs-hosted-client caveat jammed into the middle), but it does not pad for length's sake.

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 must explain return behavior, and it does: the spoken reply, the ringing/in_call statuses that trigger polling, and setup_required with an App Store link when `to` is missing. Combined with the config-file sourcing and call-lifetime semantics, an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: `question` (read verbatim, ~2000 chars / two minutes), `to` (from config.json user_number, Call Me number), `session_token` (thread continuity), `keep_open` (one-answer vs open line), and `language` (spoken language, English default). Only `from_label` is left unexplained, which is the sole shortfall for a 6-param tool.

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 sentence states a precise verb+resource chain: ring the human's iPhone, read `question` aloud word for word, return their reply. This is unambiguously distinct from siblings like `text`, `say`, and `hang_up`, and 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?

It gives concrete routing guidance: follow up with `poll_result` when status is 'ringing' or 'in_call', pass a prior `session_token` to stay in the same thread, and set `keep_open=false` to hang up after one answer. It also broadens use ('does not have to be a question'). The one gap is that it never says when to prefer the sibling `text` over placing an actual call.

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, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the goodbye string is spoken first in a keep_open conversation, and an empty value hangs up silently.

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 core action and immediately followed by the only non-obvious parameter behavior, with a concrete example. No padding, though 'leave it empty to just hang up' is slightly awkward phrasing.

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 and the description covers the key goodbye semantics, but for a destructive, open-world tool it omits what happens on error, whether the call must be active, and any auth requirements for `session_token`. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains the optional `goodbye` parameter and its default-empty behavior well, but says nothing about `call_id` or `session_token` beyond their self-evident names, leaving two required parameters effectively undocumented.

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

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

States a specific verb and resource ('End a call you placed'), which distinguishes it from the sibling `call` (which places calls) and `say` (which speaks without ending). However, it never names those siblings or explicitly contrasts scope, so an agent must infer the boundary.

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 by 'a call you placed' and the goodbye guidance tells the agent how to use the tool in a keep_open conversation, but there is no explicit when-to-use vs. alternatives statement (e.g., versus `say` or `wait_for_reply`) and no prerequisites 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?

Annotations already cover the read-only, non-destructive safety profile. The description adds important behavioral detail: it waits up to about 25 seconds, returns final status and transcript, and lists terminal conditions including call end, human decline, and ring timeout ('missed').

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

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

The description is two tightly written sentences with the core action and timeout behavior front-loaded. Every clause adds useful information with no wasted wording.

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, and the description helpfully explains what is returned and when. Still, it omits parameter meanings, especially session_token, which is a notable gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It only loosely implies what call_id means by mentioning 'a call' and says nothing about session_token, leaving both required parameters largely unexplained.

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 gives a specific verb and resource ('Check on a call') plus a clear scope ('that was still ringing or in progress'). It distinguishes this polling tool from siblings like wait_for_reply by focusing on call 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 clearly states the context for use: checking a call that is still ringing or in progress. However, it does not name alternatives or state when not to use this tool, such as for already-completed calls.

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 declare readOnlyHint=false and destructiveHint=true with openWorldHint=true; the description respects that and adds real operational context the annotations cannot convey: a ~30s wait bound, the alternative to use on 'in_call', the meaning of "open": false, and the "said_while_waiting" return field. It doesn't say what happens if the call is closed when `say` is invoked or whether the line can be retracted, so it isn't 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?

The precondition (keep_open=true call) and the core action are front-loaded, followed by the wait behavior and the field-level notes. Sentences are dense but each carries information; the quoting of "in_call", "open", and "said_while_waiting" is slightly cryptic without a schema to anchor it, which is the only structural friction.

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 does the work of describing returns by referencing the `call` shape and calling out the "said_while_waiting" field. Combined with the timeout and termination semantics, an agent has enough to call it correctly, though the unexplained call_id/session_token required parameters leave a small hole.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the burden: it explains `text` (spoken to the human) and `language` (only switches the language of the call's own lines; empty keeps it). The two required parameters `call_id` and `session_token` get no explanation at all, leaving a real gap for a call with 0% schema coverage.

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

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

The description states a specific verb and resource: speak `text` to the human and return their answer, scoped to a call placed with keep_open=true. It also ties itself to the `call` sibling by promising the same return shape. It stops short of explicitly contrasting with `text` and `wait_for_reply`, which sound semantically adjacent, so differentiation is partial rather than complete.

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 conditions are explicit and sequenced: only valid in a call placed with keep_open=true, only after the previous answer is in, and on an 'in_call' outcome the agent is told to follow up with poll_result instead. It also names the terminating condition ("open": false means the call has ended). This is the strongest dimension of the definition.

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=false and destructiveHint=true, so the agent knows this mutates state. The description adds the useful detail that the title is user-visible in the app, but never explains the destructive aspect (e.g. that it overwrites an existing title) or any auth/session 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?

Two compact sentences, front-loaded with the action and scope; the second sentence adds display context. No wasted words, though the parenthetical example could be folded more tightly.

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

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

For a simple 2-param tool with no output schema this is nearly adequate, but the unexplained destructiveHint and the undocumented session_token leave an agent guessing about overwrite behavior and session prerequisites.

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

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

Schema coverage is 0% for 2 params, so the description carries the burden. It meaningfully clarifies the 'title' parameter (project/task name, displayed as thread title) but says nothing about session_token or its format/source.

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 (name/set) and resource (this session's conversation thread) plus where it surfaces (the human's phone, app thread title). An agent can tell it apart from call/text/wait_for_reply, though it never explicitly contrasts with them.

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

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

The parenthetical 'e.g. the project or task you are working on' implies what content to pass, giving soft usage context. There is no explicit when-to-use trigger, no when-not-to-use, and no alternative 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavior context: it fires only when no number is available and it returns instructions plus a clickable download link, telling the agent what it gets back for a tool with no output schema.

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?

A single sentence that front-loads the return value and closes with the triggering condition. No filler, no restatement of the title.

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

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

For a zero-parameter, read-only setup helper with no output schema, the description tells the agent when it applies and what it returns, which is enough to invoke it correctly. Minor gaps remain around what happens if a number is already configured, but nothing critical is missing.

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

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

The tool takes zero parameters and the empty schema already makes that unambiguous. With no parameters to document, the baseline is 4; the description correctly does not invent parameter semantics that don't exist.

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 gives a concrete verb+resource: returns first-setup instructions and an App Store download link. It doesn't name or differentiate itself from siblings like call or text, but the purpose is unmistakable for a tool named 'setup' with no parameters.

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 states a condition — 'when no number is available' — which implies the agent should call this before a number is configured. However, it doesn't say what to do instead once a number exists, or name the alternative tools (call/text) that become usable. Guidance is implied rather than explicit.

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 openWorldHint=true, and the description is consistent with a write/external-send operation. It adds real value beyond the annotations: the no-ring delivery semantics, the setup_required failure path with an App Store link, and the threading behavior of session_token. It does not describe rate limits, delivery latency, or whether the send is retractable.

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 what the tool does, then setup mechanics, then threading. No filler. Slightly dense but every sentence conveys a distinct, load-bearing fact.

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, and the description compensates by naming the setup_required error case and its payload. The remaining gap is the undocumented `from_label` parameter and success-response shape, but for a single-action send tool the coverage is nearly complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does: it documents `to` (resolved from config.json → user_number) and `session_token` (continue an existing thread). `body` is left implicit and `from_label` is never mentioned, so one of four parameters has no semantics anywhere.

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 pair ('Send a one-way text to the human's phone') and immediately qualifies the channel ('push notification, no ring'). The 'one-way' framing distinguishes it from reply-oriented siblings like wait_for_reply and poll_result without needing their 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 actionable operational context: where `to` comes from on a local client, that the hosted server cannot read that file, and that a previous session_token continues the thread. It stops short of explicitly naming an alternative (e.g. 'use call/wait_for_reply when you need an answer'), so exclusions are implied rather than stated.

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

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

Annotations only declare a safe read (readOnlyHint=true, destructiveHint=false); the description adds the traits that actually matter here — that this long-polls and blocks for up to wait_s (max 30s) and returns {events, cursor}. It also pre-empts the confusing case where an empty list is not an error. Error/timeout behavior is not covered, so it is not fully 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?

Four short sentences, front-loaded with the purpose, then the blocking behavior, then the cursor contract, then the empty-result caveat. No filler and nothing repeated from the schema or annotations.

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 correctly carries the return shape ({events, cursor}) and the empty-list semantics. Combined with the safety annotations, an agent has what it needs to call this correctly. It would be complete with a note on what session_token identifies or what a timeout looks like.

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

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

Schema description coverage is 0%, so the description must carry the parameters, and it does for two of three: it explains cursor as a resume token from the prior response and wait_s as the long-poll bound with a 30s cap. session_token is left unexplained, which for a session-scoped tool is a minor gap.

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

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

The description gives a specific verb and resource: waiting for an inbound human message (texts and voicemail transcripts) on this session. It is clear about what arrives and what the call does. It stops short of explicitly contrasting itself with the sibling poll_result, which is the closest analog and would be the obvious confusion point.

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 implies when to call (while waiting for a reply) and instructs to poll again on an empty result, but never says when to prefer this over siblings like poll_result or call. No prerequisites or exclusions are stated, so the routing decision 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.