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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuine behavioral detail — messages are returned oldest first — but omits pagination/truncation behavior and what happens when limit is exceeded.

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 ten-word sentence, front-loaded with the verb and the ordering constraint. Zero filler; 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 two-parameter read tool with annotations covering safety, this is close to adequate. However, with no output schema, the description could say something about the return shape (message list, ordering, paging), which it does not.

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

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

Schema description coverage is 100%, so both parameters (chatId, limit with a stated default of 100) are already fully documented. The description adds nothing about parameters, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('one conversation'), plus the ordering guarantee ('oldest first'). It does not explicitly differentiate itself from siblings like search_messages or list_conversations, though 'one conversation' implicitly scopes it.

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 only implied: 'one conversation' suggests it follows list_conversations, but the description never says when to use this versus search_messages or inbox, nor what the chatId prerequisite implies. No exclusions or alternatives are 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?

This is the standout dimension. Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false, leaving the reason for the non-read-only hint opaque. The description explains it: a cursor is stored on disk, calling consumes it, messages received while nothing was running are not lost, and peek avoids consumption. That is exactly the behavioral context the annotations cannot convey.

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

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

Three short sentences, all load-bearing: the core scope first, then the persistence guarantee, then the non-consuming escape hatch. Nothing is redundant and the most important constraint is front-loaded.

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 three-parameter, all-optional read tool with no output schema, the description covers scope, state effects, and the peek escape hatch, which is most of what an agent needs. It omits ordering, whether results drain or repeat, and what a call returns, but these are minor given the schema carries parameter detail.

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 peek, limit, and includeFromMe are all documented in the schema already. The description's 'without consuming' restates peek's schema text rather than adding syntax or edge-case semantics, so it lands on the baseline 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 pins down a precise resource and scope: 'Messages that have arrived since this tool last ran.' That incremental/new-since-last-run framing clearly separates it from a general search, even though no sibling tool is named. It stops short of a true 5 because differentiation from search_messages and list_conversations is left implicit.

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 only implied: an agent infers it should call inbox to pull new messages rather than search. The one explicit instruction ('call with peek=true to look without consuming') is parameter-level guidance, not when-to-use-this-vs-alternatives guidance. No exclusions or sibling routing are provided.

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 cover readOnlyHint and openWorldHint, so safety is declared. The description adds that results are enriched with 'resolved contact names and participants', which is useful context. It does not disclose ordering guarantees beyond 'most recent activity', pagination behavior, or limits beyond the default 50.

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 dense sentence that front-loads the operation and result enrichment. Efficient, though terse to the point of omitting 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?

For a simple read-only list tool with annotations and full schema coverage, the description is minimally adequate. It omits return structure, pagination, and ordering specifics that would help an agent, but the operation is simple enough that this is a modest 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?

Schema coverage is 100% and the only parameter (limit) is documented in the schema with its default. The description adds no parameter detail 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?

States a specific verb (List) and resource (conversations/chats) and adds sorting scope ('by most recent activity'). It does not explicitly distinguish itself from sibling get_conversation or search_messages, so it falls 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?

No when-to-use guidance, no mention of alternatives like get_conversation or search_messages, and no exclusions. The agent must infer the use case from the name alone.

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 openWorldHint=false, so safety and scope are covered without the description. The description adds real value by disclosing the return content ('sendable handles'), which matters because there is no output schema. It does not describe ambiguity or not-found behavior, keeping it short of a 5.

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

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

Two short sentences, zero filler, with the core action front-loaded and the sequencing hint second. Nothing could be cut without losing 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 one-parameter, read-only lookup with no output schema, the description covers purpose, timing, and return content. It omits edge-case behavior such as multiple matches or no match, which is a minor gap given the tool's simplicity.

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% for the single 'name' parameter, so the description must compensate. 'By name' confirms the lookup key is a person's name in Contacts, which is slightly more than the bare schema, but it gives no format or matching guidance (full name vs. partial, ambiguity handling).

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 ('Look up a person in Contacts') plus the output ('sendable handles'), which distinguishes it from send_message and the other siblings. An agent can tell immediately this is a name-to-handle resolver, not a messaging tool.

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

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

Explicitly names the sibling it precedes ('Use before send_message') and the selecting condition ('when you know a name but not a number'). The inverse condition — you already have a number — is implicitly covered by that phrasing, so routing 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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description only needs to add beyond that. It does: it discloses that bodies are read from both the text column and the encoded attributedBody blob, explaining why results differ from a naive query. It omits pagination/ordering behavior, but the core behavioral insight is 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?

Two sentences, front-loaded with the core purpose, and the second sentence adds genuinely new information rather than padding. Nothing is wasted and the capability claim is tightly scoped.

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 read-only search tool with full annotation coverage and a fully documented schema, the description is nearly complete. With no output schema, a brief note on result shape or ordering would help, but nothing required to invoke it correctly 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?

Schema description coverage is 100%, so the schema already documents all six parameters with formats and bounds. The description only restates the filter axes at a high level and adds no syntax, matching rules, or defaults beyond what the schema provides, 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?

States a specific verb and resource ('Search message history') and enumerates the filter dimensions (text, sender, chat, date range), which map cleanly onto the schema. It is clearly distinguishable from list_conversations or get_conversation by its search semantics, though it never names a sibling explicitly.

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 — search message history when you need to find messages — and the attributedBody note hints at capability plain SQL lacks, which is a mild routing cue. However there is no explicit when-to-use versus when-not, and no guidance distinguishing it from get_conversation or inbox for retrieving message content.

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, readOnlyHint=false and openWorldHint=true, so the write/irreversible profile is covered structurally. The description adds one genuinely new behavioral fact — images and audio render inline — but does not itself restate irreversibility or the confirm requirement, which the schema carries.

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, no filler, with the core action front-loaded. It is appropriately sized, though the second sentence's rendering detail is more of a nice-to-have than essential 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?

For a destructive, no-output-schema tool this is adequate but thin: the irreversibility warning lives only in the schema's confirm description, not the tool description, and there is no indication of delivery failure modes or whether the target must be a known contact. It covers the minimum needed to call the 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?

Schema coverage is 67% and the confirm parameter already has a strong, self-contained description about irreversibility. The description only repeats the absolute-path constraint on 'path' and says nothing about 'to' or 'confirm', so it adds little 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?

States a specific verb and resource ('Send a file') plus a format constraint ('by absolute path'), which is clear enough to distinguish it from send_message. It does not explicitly name the sibling it differs from, so it falls 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?

Usage is only implied: you call this when you want to deliver a file rather than text. There is no statement of when to prefer this over send_message or transcribe_voice_note, and no prerequisites or exclusions are given.

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 annotations already declaring readOnlyHint=false, destructiveHint=true, and openWorldHint=true, the description adds real value by disclosing blocking semantics: it waits for Messages to confirm delivery and reports failure. That synchronous-confirmation behavior is not derivable from the annotations alone, and it usefully warns the agent that the call is not fire-and-forget.

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 tight sentences, front-loaded with the action and target, followed by the delivery-confirmation behavior. Nothing is wasted 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?

There is no output schema, and the description compensates by explaining the return-relevant behavior (waits for delivery confirmation, reports failures). For a mutation tool whose safety profile is carried by annotations, this is nearly complete, though the irreversibility and confirm precondition are left to structured fields.

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 67%, and the 'to' formats (handle, email, chat GUID) are already documented in the schema, so the description largely restates it. 'text' and the semantics of 'confirm' are not illuminated beyond the schema text; baseline 3 is appropriate since the schema does most of the work.

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+resource ('Send a message') and enumerates valid targets (phone number, email, chat GUID), which clearly distinguishes it from send_file and the read-oriented siblings. It does not explicitly name or contrast a sibling, but the action is unmistakable.

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 explicit when-to-use, when-not-to-use, or alternative guidance. An agent must infer that this is the tool for outbound text and that send_file covers attachments. The critical precondition (confirm must be true, only send when the user asked for this exact message) lives only in the schema, not the description.

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?

readOnlyHint=true and openWorldHint=false already establish a safe, local, side-effect-free read, so the description doesn't need to restate that. It adds useful context about what is inspected (cursor position, installed optional tools), but says nothing about cost, latency, or whether the check can fail.

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 economical clause listing the four returned categories, front-loaded with the most important item (reachability). It is a fragment rather than a sentence, but nothing is padded or wasted.

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

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

With no output schema and no parameters, the description carries the burden of describing what comes back, and it does so by enumerating the four result categories. The gap is the missing statement of purpose or invocation trigger, which would help an agent decide to call 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?

The tool takes zero parameters, so the baseline of 4 applies. The schema is trivially complete and there is nothing for the description to compensate for.

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

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

The description names the specific information the tool surfaces (reachability, cursor position, contact count, installed tools), which lets an agent distinguish it from the messaging-oriented siblings. It lacks an explicit verb, but the resource is unambiguous and no sibling tool overlaps with a status/diagnostic role.

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 statement of when to call this tool, why an agent would need it, or what condition triggers it. Nothing is misleading, but the agent must infer the use case entirely on its own.

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 destructive=true and openWorld=true, so the safety bar is partly covered; the description adds genuinely useful context: the external ElevenLabs dependency, the returned file path, and the caveat that script-sent audio renders as an attachment rather than a native voice-note bubble.

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 core action, and the second sentence carries a non-obvious rendering caveat rather than filler. Slightly dense but every clause 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?

There is no output schema, and the description compensates by stating the return value (audio file path). Combined with annotations covering the mutation profile and schema covering the send parameters, an agent has enough to call 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 75%, with `to`, `confirm` and `voiceId` fully documented in the schema. The description only reinforces the text-to-speech and optional-send semantics, adding little beyond structured fields, so baseline 3 applies.

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

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

States a concrete verb and resource: turns text into speech via ElevenLabs and returns the audio file path, with optional delivery. It is clearly distinct from the reverse-direction sibling transcribe_voice_note, though it does not name any sibling explicitly.

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 optional-send behavior is implied by 'optionally sending it' and the schema, but there is no explicit when-to-use guidance or routing versus send_file/send_message. Usage must largely be inferred.

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 and openWorldHint, so safety is covered. The description adds genuinely new behavioral context: the default provider is groq and using 'local' prevents the audio from leaving the machine, which tells the agent about data egress. It still omits rate limits, size limits, and failure 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?

Two tightly written sentences; the core action and both input modes are front-loaded with no filler.

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

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

With no output schema, the description should say what the transcription returns (text inline? stored on the message?) and how multiple attachments are handled when rowid is given. Those are real gaps for a tool whose result shape is otherwise 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?

Schema description coverage is 100%, so all three parameters are already documented. The description restates the path/rowid duality and the provider default but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Transcribe an audio attachment to text') and immediately clarifies the two ways to identify the audio. It is clearly distinguishable from siblings like speak, send_file, 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?

Explains the two input modes (message rowid vs. absolute path) and notes the default provider, plus the tradeoff that 'local' keeps audio on this machine. It stops short of explicitly stating when to prefer one mode over the other or naming an alternative tool.

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