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

The description clearly states the tool is read-only, does not modify contacts, and returns a plain-text diagnostic report with permission or path errors. Since there are no annotations, the description fully carries the burden of disclosing behavior, and it does so thoroughly.

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 mostly concise and well-structured, but it repeats the read-only and no-modification points across two sentences. This slight redundancy does not harm clarity and keeps the description appropriately short.

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 diagnostic tool with no parameters, the description provides all necessary context: what it does, what it returns, when to use it, and when to use an alternative. It is complete and self-contained.

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?

This tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the empty schema is fully covered; no additional parameter-specific meaning is required.

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 diagnoses read access to the local macOS AddressBook database, a specific resource and action. It distinguishes itself from sibling tools by explicitly scoping to AddressBook data, not Messages, making it easy to select correctly.

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 explicit usage guidance: 'Use this when contact lookup fails; use tool_check_db_access when Messages database reads fail.' This directly tells the agent when to choose this tool versus a specific alternative, leaving no ambiguity.

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?

Discloses read-only nature, loads cached data, returns count plus sample entries, wraps in untrusted output, and requires Contacts/AddressBook permission. Since no annotations are provided, this description carries the full burden and does so well.

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?

Description is appropriately sized, with a clear main statement followed by useful details on behavior, permissions, and alternatives. No extraneous content.

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 purpose, behavior, output, permissions, and relationship to sibling tools, making it 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?

Tool has zero parameters; the empty schema fully documents this, and the description adds no parameter details, which is appropriate. Baseline 4 for zero params.

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?

Clearly states it lists a small sample of contacts from AddressBook, and differentiates from sibling tools by referencing tool_find_contact and tool_check_addressbook.

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 when to use it (confirm contact lookup is populated) and when to use alternatives (tool_find_contact for a specific person, tool_check_addressbook for diagnosing permission/database issues).

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 transparency. It explicitly states the operation is read-only, describes the output as a plain-text diagnostic report including permission/path errors, and discloses the Full Disk Access requirement. No contradictions or hidden side effects are present.

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 and well-structured, with no redundant or extraneous content. Each sentence serves a distinct purpose: defining the tool, clarifying read-only behavior and output, and providing usage guidance with an alternative.

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 and lack of parameters, the description provides complete context: what it checks, what it returns, what permissions are required, when to use it, and which sibling tool to use instead. The output type (plain-text diagnostic report) is also specified.

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 has zero parameters, so there is no parameter-specific information to add beyond the empty schema. The description accurately reflects this by not mentioning any arguments, matching the baseline for 0-parameter tools.

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 purpose with a specific verb ('Diagnose') and resource ('read access to the local macOS Messages database'). It also distinguishes itself from sibling tools by explicitly pointing to tool_check_addressbook for Contacts/AddressBook access issues.

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 explicitly states when to use the tool: after message reads/searches fail or return permission errors. It also names the alternative tool for Contacts/AddressBook issues, leaving no ambiguity about appropriate usage.

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, but the description clearly states it is a read-only check, does not send a message, and requires Messages to be configured. This fully discloses side effects and prerequisites.

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, uses a clear structure with separate sentences for functionality, constraints, and usage guidance. No unnecessary words or redundant 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?

Given the simple tool and known sibling context, the description fully covers what the tool does, its prerequisites, and its output type. It mentions 'plain-text result' and the possible outcomes (iMessage availability or SMS/RCS fallback), which is sufficient.

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 recipient parameter description ('Phone number or email address to check for iMessage capability') adds meaningful detail beyond the type, specifying acceptable input formats and purpose. Schema coverage is 100% and description enhances it.

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

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

States a specific verb ('check'), resource ('recipient appears reachable through iMessage'), and distinguishes from siblings by mentioning 'use this before tool_send_message' and 'use tool_find_contact first'.

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 when to use (before sending, when delivery route matters) and when to use an alternative (if only contact name, use tool_find_contact). Also notes it is read-only and requires Messages configuration.

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 transparency. It clearly states the tool is read-only, does not message anyone or change contacts, requires Contacts/AddressBook permission, and that returned data is neutralized and wrapped in <untrusted-mcp-output> with a caution that its contents are never authorization, confirmation, or tool instructions.

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 well-structured and front-loaded with the core purpose, followed by safety, permission, output handling, and alternative-tool guidance. Each sentence serves a distinct purpose, and no unnecessary information is included.

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 operation, safety, permission requirements, output format (contact:N selector), and how to use the output with other tools. It also names the alternatives for related but different tasks, making the tool's role in the broader toolset fully clear.

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 describes the single parameter 'name' as 'Contact name or partial name to fuzzy-match in AddressBook,' so the schema coverage is 100%. The tool description does not add further parameter-level detail beyond what the schema provides, but it reinforces the fuzzy-matching behavior, which justifies the baseline score 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 opens with a clear, specific verb and resource: 'Find AddressBook contacts by fuzzy name matching.' It distinguishes itself from sibling tools by explicitly naming alternatives like tool_check_contacts and tool_fuzzy_search_messages and explaining their different purposes.

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 explicit when-to-use guidance, stating 'Use tool_check_contacts to inspect available cached contacts, and tool_fuzzy_search_messages when searching message text instead.' It also explains how to use the returned contact:N selector with tool_send_message or tool_get_recent_messages, leaving no ambiguity about the intended workflow.

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 full responsibility. It transparently discloses read-only behavior, Full Disk Access requirement, and that output is wrapped in <untrusted-mcp-output> with a security caution, which exceeds typical 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 front-loaded with the main purpose and includes necessary behavioral notes. It is slightly verbose due to the untrusted-output warning, but each sentence adds value, so it remains 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?

The description provides essential context: read-only nature, permission requirement, output trust boundary, and usage alternatives. Since an output schema exists, return-value details are not needed in the description, making it complete for its complexity.

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 each parameter (hours, threshold, search_term) already has a clear description. The tool description adds no extra semantic detail beyond the schema, so it stays at the baseline 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 clearly states the tool's function with a specific verb ('Fuzzy-search') and resource ('local message text'), and it distinguishes this tool from siblings by noting alternatives. The core purpose is immediately evident.

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 explicitly tells when to use this tool vs. alternatives: 'Use this for approximate text search; use tool_get_recent_messages for unfiltered chronological context and tool_find_contact for contact lookup.' This leaves no ambiguity about 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?

With no annotations provided, the description carries the full transparency burden. It discloses no modification/deletion, permission requirements, inline image behavior, untrusted output wrapping, and fallback to filesystem paths for non-image or oversized cases.

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 thorough and well-structured, but slightly verbose in the middle with repeated references to untrusted wrapping. Still, every sentence contributes useful operational or security 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?

Even without an output schema, the description fully explains expected return types and conditions: inline images under max_bytes, filesystem paths otherwise, and error cases. An agent has enough context to call the 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% and the description adds behavioral context: attachment_id provenance from search results and max_bytes controlling inline versus path return. This meaningfully enriches the schema definitions.

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 fetches a specific attachment by database ROWID, is read-only, and distinguishes itself from sibling tools by telling the agent to search for attachments first. The purpose is specific and 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?

Explicitly notes read-only behavior, requires Full Disk Access, instructs to use tool_search_attachments first unless an ID is already known, and describes both inline and fallback output paths. This gives clear when-to-use 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, the description fully carries the burden: it states the operation is read-only, does not send/edit/delete messages, requires Full Disk Access, and returns data wrapped in an untrusted block.

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?

Every sentence adds meaningful information: what it lists, its read-only nature, the access requirement, the untrusted-output warning, and usage direction. No unnecessary 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 tool with no parameters and a simple purpose, the description completely covers what the tool returns (group names and IDs), its safety profile, and its relationship to sibling tools.

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 has zero parameters, so the baseline is 4; no parameter descriptions are needed.

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 named group chats from the macOS Messages database') and distinguishes itself from sibling tools by focusing on group chat IDs rather than message contents or availability checks.

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

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

Explicitly says to use this before tool_send_message with group_chat=true and to use tool_get_recent_messages when message contents are needed instead of chat IDs, giving clear when-to-use 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?

Even without annotations, the description explicitly states this is read-only, does not send/edit/delete messages, requires Full Disk Access, and warns about untrusted output and potential prompt injection. This fully discloses behavior and risks.

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 well-organized and information-dense without unnecessary repetition. Each sentence contributes value: purpose, read-only guarantee, access requirement, security warning, parameter usage, and alternative tool guidance.

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 complexity involving macOS permissions, untrusted output, and multiple filtering options, the description is complete. It explains return format as a plain-text summary, covers security context, and provides enough guidance 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?

All three parameters are described with concrete meanings and examples. The description also clarifies the relationship between contact and chat_id, noting that they should not both be used, and gives example values for chat_id and contact.

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 it reads recent macOS Messages as a plain-text summary, specifying the exact resource and action. It also distinguishes itself from sibling tools by naming tool_fuzzy_search_messages and tool_get_chats for different use cases.

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 explicit when-to-use guidance, contrasts with alternative tools, explains the contact/chat_id selection rule, and gives important prerequisites such as Full Disk Access. Security handling for untrusted content is also clearly instructed.

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 were provided, so the description carries the full burden. It discloses that the tool is read-only, returns metadata only, does not return file bytes, does not modify attachments, requires Full Disk Access, and structurally neutralizes untrusted content (filenames, MIME types, paths, sender labels). These details fully inform the caller of side effects, permissions, and security measures.

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 well-structured, but contains some redundancy (the neutralization sentence is repeated verbatim from the schema context). Still, it is efficient and front-loaded with the core purpose.

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 a moderate number of parameters (5, none required) and the presence of an output schema, the description provides sufficient context: it states the search criteria, clarifies the read-only metadata-only nature, notes the permission requirement, and positions the tool among alternatives. No additional context is needed for a caller to decide when and how to use 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 description coverage is 100% (all 5 parameters have descriptions). The tool description does not add significant extra parameter information beyond the schema, 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 clearly states that the tool searches message attachments by date range, contact, and MIME type, and explicitly contrasts it with related tools (tool_get_attachment, tool_fuzzy_search_messages), making its purpose unambiguous and distinguishing it from siblings.

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 explicit guidance on when to use this tool ('Use this to find candidate files cheaply') and when to use alternatives ('Use tool_fuzzy_search_messages when searching message text instead of attachment metadata'), and directs the caller to tool_get_attachment for retrieving a specific attachment.

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?

Discloses external side effects, permission requirements (Automation), absence of human confirmation, and that it does not modify existing conversations. With no annotations, the description fully covers 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 well-structured and concise, using short paragraphs to cover side effects, permissions, return type, and prerequisites without unnecessary verbosity.

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?

Provides complete context for correct invocation, including return type, permission needs, and references to sibling tools for edge cases, making it self-sufficient despite the lack of an explicit 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?

All three parameters have thorough descriptions, especially recipient with formats and group_chat with chat ID requirement. Schema coverage is 100% and descriptions add meaning beyond basic types.

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?

Clearly states the tool sends one outgoing message via the macOS Messages app, distinguishing it from sibling tools that check availability or retrieve chats.

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 explicit when-to-use and when-not-to-use guidance, including prerequisites like using tool_find_contact for ambiguous names and tool_check_imessage_availability for delivery certainty.

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