Call Me

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

Adds important behavioral context beyond annotations: waits up to 30 seconds, returns a status that may be 'ringing', and the `to` number is a special /call-me number, not a real phone. While annotations already indicate non-read-only and destructive, this description enriches understanding of side effects.

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

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

The description is concise and structured effectively, with three sentences covering purpose, behavioral details, and parameter nuances. Each sentence adds value without redundancy.

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

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

The description covers the essential aspects: action, waiting time, status handling, the special `to` number, and session token. It lacks details about the exact return format and the `from_label` parameter, but these are relatively minor given the tool's straightforward nature.

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

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

The schema has 0% description coverage, so the description must explain parameters. It clarifies `to` and `session_token` well, and `question` is inferable from the tool's purpose. However, `from_label` is not explained, leaving a gap in parameter semantics.

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

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

The description clearly states the tool's function: ringing the human's iPhone, asking a question aloud, and returning their response. It uses a specific verb and resource, and is distinct from siblings like text or poll_result by describing the spoken interaction.

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

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

Provides clear guidance on when to use the tool and next steps: it specifies following up with poll_result if the status is 'ringing' and explains the nature of the `to` number and session_token. However, it does not explicitly contrast with all sibling tools or state when not to use it.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description discloses waiting behavior (~25s), possible outcomes (answers, declines, missed), and that it returns a transcript. This adds valuable context without contradicting annotations.

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

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

The description is a compact two-sentence structure, front-loaded with the core purpose and followed by concise behavioral details. Every word earns its place.

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

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

For a simple read-only polling tool with no output schema, the description covers what it does, when to use it, how long it waits, and what it returns. It is complete enough for an agent to invoke it correctly.

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

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

The schema has no descriptions for the two parameters (0% coverage), and the description does not compensate by explaining 'call_id' or 'session_token'. While the names are somewhat self-explanatory, the description adds no explicit semantics beyond the schema.

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

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

The description uses a specific verb ('Check'), names the resource ('a call that was still ringing'), and clearly describes the outcome (returns final status and transcript). It distinguishes from siblings like 'call' (initiation) and 'wait_for_reply' (text reply) by focusing on polling a ringing call.

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

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

The description implies the usage context: use it when a call was still ringing and you need to wait for the outcome. It does not explicitly name alternatives or exclusions, but the context is clear enough relative to sibling tools.

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

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

Annotations already indicate destructiveHint=true, so the description's mention of 'Name' and 'thread title' adds context that this changes a persistent label. This is consistent with the annotations and clarifies the effect without being misleading.

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 convey the purpose and the visual context without waste. Every clause adds meaningful information.

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

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

For a simple setter with only two self-explanatory parameters and no output schema, the description is sufficient. It tells the agent the effect and where the title appears. Minor gaps like whether it overwrites an existing title are not essential for basic usage.

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 for parameter meaning. It does not explain session_token or title, relying solely on their names. The description adds no value beyond the schema's field names, leaving a gap for a critical token parameter.

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

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

The description clearly states the action ('Name this session's conversation thread') and specifies the resource and context ('on the human's phone', 'thread title in the app'). This distinguishes it from sibling tools like call or text, which handle communication rather than session naming.

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

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

The description implies when to use it (when you want to label the current session with a project or task). It doesn't explicitly state when not to use it or mention alternatives, but the sibling tools are clearly different in function, so the context is clear.

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

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

The description adds behavioral context beyond annotations by specifying it's a push notification with no ring and one-way (no response expected). It also explains thread continuation via session_token. This complements the destructiveHint and openWorldHint annotations without contradicting 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?

Two sentences, front-loaded with the verb and purpose, followed by parameter clarifications. No unnecessary 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?

The description covers the tool's core behavior and key parameters, and annotations handle safety. It doesn't document return values (no output schema) or failure behavior, but for a simple one-way messaging tool this is adequate. The unexplained from_label is a minor gap.

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

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

With 0% schema coverage, the description compensates by explaining `to` as a 10-digit /call-me number and `session_token` for staying in the same thread. `body` is self-explanatory, but `from_label` remains unexplained, leaving a 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 uses a specific verb 'Send' and clearly identifies the resource as a one-way text to the human's phone, with clarifying details (push notification, no ring) that distinguish it from sibling tools like call. The scope is unambiguous and not a tautology.

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 provides context for use (one-way text with no ring, session_token for threading) but does not explicitly mention alternatives or when not to use it relative to siblings like call or wait_for_reply. However, the context is clear enough to infer its place.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context: long-polling up to wait_s (max 30s), the return shape {events, cursor}, the need to pass the cursor for delta reads, and the meaning of an empty events list. This goes well beyond the annotations and gives the agent a clear mental model of the tool's runtime behavior.

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

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

The description is compact yet information-dense. It front-loads the purpose, then delivers the essential mechanics (long-poll, return shape, cursor, empty list behavior) in two sentences. Every phrase adds value with no filler or redundancy.

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

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

Given the tool's simplicity, the description covers all key aspects: what it waits for, the polling timeout, the return structure, and the cursor-based pagination. There is no output schema, so the description's explanation of {events, cursor} is essential and complete. No major behavioral edge cases are ignored for this use case.

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 explain parameters. It does explain cursor ('Pass the returned cursor next time') and wait_s ('Long-polls up to wait_s (max 30s)'). Session_token is not explicitly described, but its name and the 'session' context make its role obvious. The description compensates well for the schema's lack of parameter documentation, though it could have been more explicit about session_token.

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 immediately states the tool's purpose: 'Wait for the human to send something back to this session.' It specifies the resource (human replies), the verb (wait), and the content (texts and voicemail transcripts). This clearly distinguishes it from siblings like 'text' (sending) and 'call' (initiating a call).

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

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

The description provides clear context on when to use this tool: after sending something, to wait for a reply. It explains the polling pattern ('poll again if you are still waiting') and the cursor usage. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a full 5.

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