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

With no annotations, the description carries the disclosure burden and does well by explicitly stating 'This is best-effort because Apple does not expose a direct preflight availability API.' This warns the agent about reliability limitations. It does not elaborate on possible failure modes or whether the tool is read-only, but 'inspect' implies no mutation.

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, no filler, front-loaded purpose statement, and a meaningful caveat. Every sentence earns its place.

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

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

For a simple two-parameter pre-send detection tool, the description covers the core behavior, output categories (iMessage, SMS/RCS, or auto), and the key limitation. It lacks a detailed return structure, but the described output types are sufficient for agent 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 100%, so the schema already documents both parameters. The description adds no parameter-specific detail beyond implying the recipient in 'for a recipient,' so the baseline of 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 uses a specific verb-resource pairing: 'Inspect local Messages history for a recipient and recommend iMessage, SMS/RCS, or auto before sending.' It clearly distinguishes itself from sending tools like send_message and read/search tools by focusing on pre-send service detection.

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: use this before sending to determine the best message service. It does not explicitly name alternative tools or state when not to use it, but the 'before sending' phrasing gives a practical usage trigger.

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?

With no annotations, the description carries the burden of behavioral disclosure. It does state that the tool returns structured candidates with status, risk labels, and evidence snippets, implying a read/classify operation. However, it does not explain how risk or follow-up status is determined, what status values are possible, or whether the tool only inspects outbound Tyler messages.

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 one focused sentence that states the action, the resource, and the output shape. It has no redundant clauses, does not duplicate schema details, and is easy to scan.

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

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

For a tool with 4 optional and fully documented parameters and no output schema, the description does a solid job by noting what kinds of results are returned. It would be more complete with explicit mention of what status/risk labels mean or an example, but the overall complexity is low enough that the current description is adequate.

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

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

The input schema covers all four parameters with complete descriptions, so the description does not need to restate them. The schema descriptions already explain the meaning of limit, hours_ago, max_results, and outreach_terms, and the description itself adds little parameter-level 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 uses the specific verb 'Find' with a distinct resource ('SMS outreach conversations that need agent review or follow-up') and clearly names what is returned: structured candidates with status, risk labels, and evidence snippets. This distinguishes it well from sibling tools like read_recent_messages or search_messages, which are more general chat lookup tools.

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

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

The description clearly implies the intended use case: triage or surface SMS outreach conversations that an agent should review or follow up on. It gives clear context but does not explicitly name alternative tools or exclusion conditions, so it falls just short of fully explicit usage guidance.

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

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

With no annotations provided, the description carries the transparency burden. It discloses a key behavior: 'Returns images directly so Claude can view and analyze them,' which indicates the response format is the file content itself, not a URL or metadata. This adds value beyond what the input schema specifies, though it doesn't detail error handling or non-image file 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 two sentences, front-loaded with the primary action and followed by a helpful clarification. No unnecessary words, every sentence earns its place.

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

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

For a tool with one parameter and no output schema, the description covers the core purpose, return behavior, and required input source. It doesn't mention error cases or file type limitations, but the simplicity of the tool makes this acceptable. Overall, it provides enough context 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?

Schema coverage is 100%, and the schema already fully documents the only parameter, message_id, including its origin ('from conversation results'). The description repeats this guidance but adds no new meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get an attachment (image, file) from a message.' It also adds purpose nuance by explaining that images are returned directly for viewing and analysis, which distinguishes it from sibling tools that read messages or retrieve conversation metadata.

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 by specifying the prerequisite: 'Use message IDs from get_conversation results.' This tells the agent exactly where to obtain the required parameter. It doesn't explicitly discuss alternatives or exclusions, but the purpose is distinct enough among siblings that this guidance is sufficient.

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

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

With no annotations, the description carries full burden. It mentions output includes text content and attachment indicators, and implies read-only behavior via 'get', but does not detail permissions, rate limits, or any side effects. This partial disclosure merits a mid-range score.

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 (two sentences) and front-loaded with the main purpose. It avoids redundancy and captures the core functionality efficiently.

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 sibling tools include similar functions like get_conversation_by_chat_id, the description does not clarify the unique value or conditions for using this tool over others. It also leaves ambiguity about whether 'full thread' implies all messages or a summary, and does not mention output format. This incomplete context warrants a mid-range score.

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?

All four parameters have descriptive comments in the schema (100% coverage). The descriptions add meaning, such as clarifying 'phone_number' as an alias for 'contact' and explaining the purpose of 'hours_ago'. This exceeds the baseline for full 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 clearly states the tool retrieves a full conversation thread with a specific contact or phone number, optionally filtered by time. It distinguishes itself from siblings like 'read_recent_messages' and 'search_messages' by specifying the retrieval scope and criteria.

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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., get_conversation_by_chat_id, search_messages). It only states what the tool does, leaving the user to infer the appropriate context.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does not mention side effects, permissions, rate limits, or whether the operation is read-only. The phrase 'as structured JSON' hints at output format but does not describe error behavior, pagination, or any constraints. For a read-like operation with no annotations, this is insufficient.

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

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

The description is a single, compact sentence that is front-loaded with the purpose and contains no redundant words. It includes a practical hint about obtaining the chat_id without unnecessary elaboration. Every word earns its place, making it highly concise and well-structured.

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 (3 params, no output schema, no annotations), the description is minimally sufficient. It covers the core purpose and provides a source for chat_id, but lacks additional context like whether the response includes message details, attachments, or any limits. Since schema descriptions cover the parameters, the description does not need to repeat them, but it could mention expected output structure or typical use cases. It is adequate but leaves some gaps for a fully informed decision.

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

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

The schema description coverage is 100%, so parameters are already well-documented. The description adds value by clarifying the source for 'chat_id' (from list_chats_structured or find_outreach_followups), which is a practical semantic detail beyond the schema's generic 'The iMessage chat ROWID.' This justifies a score above the baseline of 3.

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: 'Get a conversation by iMessage chat_id as structured JSON.' It specifies the resource (conversation), the identifier (chat_id), and the output format (structured JSON). It distinguishes itself from siblings by focusing on chat_id lookup and even mentions where to obtain the chat_id from, which adds clarity.

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

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

The description gives contextual guidance by instructing the agent to 'Use chat_id from list_chats_structured or find_outreach_followups.' This indicates the typical workflow and source for the input parameter. However, it does not explicitly state when to use this tool versus alternatives like 'get_conversation' or 'read_recent_messages', nor does it mention exclusions or prerequisites beyond the chat_id source.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only mentions output fields and 'structured JSON'; it does not state whether the operation is read-only, how results are ordered, whether default filtering applies, or any rate limits. This is minimal behavioral transparency.

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

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

The description is a single, focused sentence that front-loads the core action ('List recent chats') and then specifies the output format and fields. Every word contributes value, with no redundancy or 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 simple tool with two optional parameters and no output schema, the description provides the essential return fields, which is reasonably complete. However, the lack of differentiation from the sibling 'list_recent_chats' and the unexplained 'recent' behavior leave clear gaps for fully informed use.

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?

Both parameters are fully described in the input schema (100% coverage), so the description does not need to add parameter details. It also does not add any additional semantics beyond what the schema provides; 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 clearly states 'List recent chats as structured JSON' and enumerates specific output fields (chat IDs, handles, last sender, last message preview, group status, message counts), which makes the tool's function and return format evident. However, it does not explicitly differentiate this tool from the similarly named sibling 'list_recent_chats', so it stops short of a 5.

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 no guidance on when to use this tool versus the sibling 'list_recent_chats' or other chat retrieval tools. There is no mention of alternatives, exclusions, or preferred use cases, leaving the agent without context for selection.

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?

No annotations are provided, so the description must convey behavior. It clearly indicates a read-only operation (list) and specifies the criteria (recent, outgoing, failed/pending/recovered). It doesn't mention side effects, but as a listing operation, it's reasonably transparent. It could be clearer about whether it modifies anything, but it's unlikely given 'List'.

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 (two sentences) and directly states the purpose and use case. No unnecessary words 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?

The description provides sufficient context for the tool's behavior and purpose. Since there is no output schema, the description does not explain the return format, but it's implied that it returns a list of delivery failures. The absence of explicit output details is a minor omission but not critical for this simple tool.

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

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

Each parameter (limit, hours_ago, include_pending) has a descriptive explanation in the schema, covering 100% of parameters. The descriptions are clear enough for a user to understand their purpose, though 'include_pending' could be more precise about the condition 'error is 0'.

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: listing recent outgoing messages that failed, are pending, or potentially recovered via SMS/RCS fallback, with a concrete use case (finding red 'Not Delivered' bubbles). This distinguishes it from sibling tools like read_recent_messages or search_messages.

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 a specific use case ('Use this to find red Not Delivered bubbles'), which implies when to use it. However, it does not explicitly mention when not to use it or compare with alternatives, but the purpose is narrow enough that this is not a major gap.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the sort order and does not explain what 'active' means, how 'hours_ago' affects results, or any edge-case behavior. This is minimal and leaves several operational aspects ambiguous.

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

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

The description is a single, well-structured sentence that front-loads the action with 'List' and efficiently conveys the core behavior. Every word contributes to meaning, with no unnecessary elaboration, making it highly concise.

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 list with two optional parameters, the description is adequate but not comprehensive. It doesn't clarify how 'limit' and 'hours_ago' interact, what 'active' means in this context, or whether any pagination strategy exists. The absence of an output schema makes the return type implicit (a list), but overall the description leaves some user-visible behavior unexplained.

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

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

The input schema covers both parameters ('limit' and 'hours_ago') with descriptions, resulting in 100% schema coverage. The tool description adds no additional parameter semantics beyond what the schema already provides, meeting the baseline of 3 for high 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 uses a specific verb 'List' and clarifies the resource as 'recent active conversations' with a sorting criterion, which is clear and action-oriented. However, it does not distinguish itself from sibling tool 'list_chats_structured', so the purpose is clear but not fully differentiated.

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?

There is no mention of when to use this tool versus alternatives like 'list_chats_structured' or 'search_messages'. The description implies a use case for recent chats but provides no explicit guidance, alternatives, or exclusions, leaving the agent without help in choosing among siblings.

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?

No annotations are provided, so the description carries full responsibility. It implies a read-only lookup but does not explicitly state safety, behavior on no match, or whether multiple results may be returned. The description is minimal and lacks behavioral transparency beyond the basic 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?

The description is a single, concise sentence that conveys the purpose and expected output without unnecessary words. It is appropriately front-loaded with the action and resource.

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

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

The tool is simple with one parameter and no output schemachers. The description covers the core functionality well, but it doesn't specify behavior for ambiguous cases (e.g., multiple matches, no match) or explicitly state read-only nature. Given the simplicity, a 4 could be argued, but the lack of any behavioral detail beyond the core action lowers it.

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

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

Schema coverage is 100% — the parameter 'name' has a clear description with examples. The tool description does not add additional parameter semantics beyond what the schema already provides, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: looking up a contact in macOS Contacts to retrieve phone number or email. The verb 'Look up' is specific, the resource is identified (macOS Contacts), and the intended output is explicit. It distinguishes from siblings which are message-related.

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 tool is for finding contact information but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. Since all siblings are message-related, the context is clear, but explicit guidance is missing.

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?

With no annotations provided, the description carries the full burden. It discloses the confirmation requirement and lists supported reactions, but does not detail permission requirements or reversibility. The core behavioral constraint (confirmation) is clearly communicated.

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 sentences, front-loaded with purpose and followed by a critical safety instruction. No redundancy or wasted words.

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

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

For a low-complexity tool with exhaustive schema descriptions, the description covers purpose and the key confirmation behavior. It does not explain return values, but no output schema exists and the tool's behavior is straightforward.

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 description need not add parameter details. The description does restate the emoji mapping but adds no new parameter semantics beyond the schema's existing descriptions.

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: 'React to a message with an emoji,' enumerating specific emoji options. This distinguishes it from sibling tools like send_message or read_recent_messages.

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 instructs the agent to 'Always show the user which message and reaction before sending, and get explicit confirmation,' providing a clear safety protocol. It does not explicitly name alternatives, but the action (reaction vs sending) is unambiguous.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention that this is a read-only operation (though 'read' implies it), nor does it describe any side effects, permissions, or limitations. The description is minimal and does not add context beyond the tool's 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?

The description is a single, concise sentence that is front-loaded with the core purpose. It is appropriately sized with no wasted words, though it could benefit from a bit more detail on usage context.

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 (2 params, no output schema), the description is somewhat complete but lacks context on what the returned messages look like, how they are ordered, or any limitations. With no annotations and no output schema, the description should provide more behavioral context to be fully 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 100%, so the schema already documents both parameters (limit and include_group_chats) with defaults. The description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool reads recent iMessages from the Messages app, which is a specific verb+resource. It distinguishes from siblings like search_messages and get_conversation by focusing on 'recent' messages, though it doesn't explicitly differentiate from list_recent_chats which might be similar.

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

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

The description implies usage for reading recent messages but does not provide explicit guidance on when to use this tool versus alternatives like search_messages or get_conversation. No exclusions or alternative tool mentions are given, so the agent must infer context from the name and siblings.

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?

There are no annotations to disclose read-only or destructive behavior. The description only mentions 'search', suggesting a read operation, but does not explicitly state that it does not modify data, nor does it mention authentication or rate limits. It does not contradict any annotations (none provided), but it fails to carry the burden of behavioral disclosure without 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?

The description is a single, well-formed sentence that directly states the tool's purpose without any filler. It is front-loaded and concise, ideal for an agent to quickly understand the tool's function.

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

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

For a tool with only 2 parameters and no output schema, the description is adequate but minimal. It does not describe the return format (e.g., message objects, IDs, or metadata), nor does it mention pagination or result sorting. While the simplicity of the tool lowers the bar, the description omits details that would help an agent anticipate the response shape, making it incomplete.

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

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

The schema already provides 100% coverage, documenting both parameters. The description's phrase 'by contact name, phone number, or message content' mirrors the schema's description of query, adding no new meaning. The limit parameter is not mentioned, but its schema description is sufficient. Since the schema does the heavy lifting, the description adds minimal value beyond 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?

The description clearly states the tool searches for messages using specific criteria (contact name, phone number, or content). It distinguishes from siblings like read_recent_messages (retrieves recent messages) and get_conversation (fetches a full conversation). The verb 'search' plus the resource 'messages' and the scope of search fields make the purpose unambiguous.

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

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

The description implies when to use the tool: when you need to find messages by contact details or content. However, it does not explicitly contrast with alternatives like read_recent_messages or list_chats_structured, nor does it state when not to use it. The guidance is clear but not exhaustive.

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?

With no annotations, the description carries the full burden and does well: it discloses AppleScript reliance, iMessage vs SMS/RCS behavior, auto-detection fallback, and the confirmation requirement. It could be more transparent about failure behavior or permissions, but the key behavioral traits are clearly stated.

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: two sentences, front-loaded with the core action, and no filler. The IMPORTANT warning earns its place because it encodes a critical safety workflow. Redundancy with the schema is minimal and acceptable.

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

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

For a single-send tool with moderate complexity, the description covers the main invocation context: recipient types, service selection, fallback behavior, and confirmation. It doesn't detail delivery outcomes or error paths, but those are plausibly covered by sibling tools and are not essential to selecting and invoking 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by explaining blue/green bubble semantics, the auto fallback behavior tied to the service parameter, and reinforcing the confirm parameter's real-world purpose with the 'IMPORTANT' note.

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

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

The description opens with a specific verb and resource: 'Send an iMessage or SMS/RCS to a contact.' It clearly distinguishes itself from send_message_batch by describing a single message to a single contact, and adds concrete context with blue/green bubble terminology and AppleScript mention.

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 usage for sending one message and provides the important workflow requirement to show content and get confirmation. However, it does not explicitly say when to use this tool versus siblings like send_message_batch or detect_message_service, nor does it list exclusions or alternatives.

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?

With no annotations provided, the description carries the full burden of disclosing behavior. It reveals the two-phase safety mechanism (preview token, confirm=true, exact batch required) and implies preview does not send. It does not describe failure modes, token expiry, or send results, but the core behavioral safeguard is clearly disclosed.

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 sentences and immediately front-loads the core purpose. Every sentence contributes: the first states what the tool does, the second explains the critical preview/send workflow. 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?

For a two-mode batch messaging tool with no output schema, the description covers the essential workflow well. The main gap is that it does not describe what the send call returns or what happens on unsuccessful validation, but the schema and the preview-token explanation provide enough context 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 100%, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining how approval_token, confirm, and items interact: preview returns a token, and sending requires the same batch plus confirm=true plus that token. This helps the agent correctly sequence calls.

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: 'Preview or send a reviewed SMS/iMessage batch.' It specifies the resource (batch of messages), the two distinct operations (preview vs send), and implicitly distinguishes itself from the singular sibling tool send_message by focusing on batch operations.

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 operational context: preview first to obtain an approval token, then send with confirm=true and the matching token. It does not explicitly name alternative tools or state when not to use this tool, but the batch-focused workflow and mention of 'the same exact batch' give sufficient usage guidance.

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