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

Discloses async nature, caching, request anchoring, that WhatsApp controls how far back it serves, and return fields (cacheBefore/cacheAfter). No annotations provided, so description fully handles 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?

Concise paragraph with clear flow: purpose, mechanism, limitation, return info. Every sentence adds value.

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 no output schema, description explains return values and what to do if results are poor. Covers async behavior, caching, and fallback sufficiently for an agent.

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 covers 100% of parameter descriptions, so baseline 3. Description does not add new parameter-level detail beyond context but reinforces usage context.

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 recovers missed WhatsApp messages when the bridge was offline, with specific verb 'recover' and resource 'history'. Distinguishes from siblings like relink_whatsapp by positioning it as a fallback.

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 when to use ('bridge was offline') and when not to expect full history (WhatsApp decides). Provides alternative (relink_whatsapp) if messagesAdded is ~0.

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. It discloses idempotency (skips already-transcribed) and that it no longer touches images. It does not cover rate limits, auth needs, or error conditions, but the key behaviors are transparent.

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 with a clear opening sentence, idempotent note, important caveat about images, and a enumerated workflow. It is concise but every sentence adds value, though the workflow could be slightly tighter.

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 no output schema and only 3 parameters, the description provides good context but leaves gaps: 'maxItems' and 'concurrency' are undocumented, and there is no mention of error handling or prerequisites (e.g., linked account). The workflow is helpful but incomplete for complex scenarios.

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

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

Schema coverage is 0%, so the description must compensate. It explains the 'hours' parameter ('last N hours') but does not explain 'maxItems' or 'concurrency' explicitly. While 'concurrency' might be inferred from context, the agent gets incomplete parameter guidance.

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 does voice-only enrichment by downloading and transcribing voice notes via OpenAI Whisper. It explicitly contrasts with image processing, distinguishing it from siblings like get_image and set_description.

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: it is for voice enrichment only, and provides a step-by-step workflow (1) call enrich_window, (2) call get_image and set_description for images, (3) call get_recent_messages to write briefs. It also mentions that image analysis is done by Claude via get_image, clearly separating responsibilities.

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 must disclose behavior. It states the action (reconnect socket) but does not elaborate on side effects (e.g., message loss, interruption of ongoing operations) or required permissions. Adequate for a simple action but lacks depth.

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 purpose, then usage guideline. No wasted words, efficient and clear.

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 no parameters, output schema, or annotations, the description provides necessary purpose and usage context. Could mention potential disruptions from reconnection, but overall sufficient for a 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?

No parameters in input schema, and schema coverage is 100% trivially. Baseline for zero parameters is 4. Description adds no parameter info, which is acceptable.

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 verb 'Reconnect' and the resource 'WhatsApp socket', defining a specific action. It implies a manual intervention tool, which distinguishes it from automatic bridge behavior, but does not explicitly differentiate from the sibling tool 'relink_whatsapp'.

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 tells when to use ('only when chats look stale') and when not to ('normally the bridge keeps itself connected'), providing clear context and 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, the description fully discloses behavior: it reads a specific file and returns a brief or null. No side effects are implied, which is appropriate for a read operation. Could mention if the file might be empty or locked, but not required.

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?

One sentence, no fluff, action-first, and all key information included. Every word carries meaning.

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 zero parameters and no output schema, the description sufficiently explains what the tool does, what it returns, and the edge case (null). No missing context for the simplicity of 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?

No parameters exist, and schema coverage is 100% (no params). Baseline is 4; the description correctly omits parameter info as unnecessary.

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

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

The description clearly states the action ('Return'), the resource ('most recently generated brief'), and the file location ('data/brief.json'), with a clear return behavior ('or null if none exists'). It is distinct from siblings like 'set_brief' or 'get_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?

The description implies usage for retrieving the latest brief, but does not explicitly state when to use this tool versus alternatives (e.g., 'set_brief' for creating, 'get_recent_messages' for other data). No when-not or alternative mention.

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, description fully carries burden. Discloses return format (inline bytes for Claude), graceful failure on missing/expired media, and implicit read-only nature. Could mention if any side effects occur, but download implies none.

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 purpose and usage. Efficient but could be slightly more structured (e.g., separate usage and behavior).

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

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

No output schema, but describes return format and error cases. Covers essential aspects for a simple image retrieval tool. Adequate for the 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 has 0% coverage (no descriptions), but description adds meaning: msgId and chatId come from get_recent_messages results. This compensates well for the lack of schema 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 downloads a cached image and returns bytes inline for Claude to see, mentioning a specific use case (Opus vision) and distinguishing from siblings like get_recent_messages and save_image.

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 context: pass msgId and chatId from get_recent_messages when hasMedia=true and type=imageMessage. Mentions failure conditions (missing keys, expiry). Lacks explicit 'when not to use', but context 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?

Discloses that messages include human-friendly names and IDs are for follow-up calls. However, with no annotations, it omits behavioral traits like data freshness, caching behavior, or any side effects (e.g., cache invalidation).

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 concise, front-loaded sentences with no redundancy. Every sentence adds value: purpose, return field format, and usage warning.

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?

Adequate for a simple retrieval tool but lacks explicit return structure (only mentions 'chat' and 'from' fields) and does not specify pagination or empty cache behavior. Given many siblings, could hint at differentiation.

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

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

With 0% schema description coverage, the description explains three of four parameters (hours, chatId, excludeGroups) in context but misses 'limit'. The explanations add meaning but are incomplete.

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 retrieves messages from the last N hours from local cache with optional filtering. The verb 'get' and resource 'messages' are specific, though it doesn't explicitly distinguish from sibling tools like 'search_messages' or 'get_brief'.

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 implicit guidance on when to use (for recent messages) and how to handle IDs, but lacks explicit when-to-use vs alternatives (e.g., 'search_messages' for richer queries) and no exclusions or prerequisites.

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 transparency. It indicates a read-only operation ('Return...') but does not explicitly state side effects, authentication requirements, or rate limits. While it implies no side effects, more detail would be beneficial.

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. It front-loads the core purpose ('Return current WhatsApp connection status') and follows with specific examples. Every word contributes to understanding, with no redundancy or waste.

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 zero parameters and no output schema, the description is mostly complete. It lists the types of information returned. It could mention that it is a quick, non-destructive operation, but the current text is adequate for an agent to use 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?

The tool has zero parameters, so the schema provides 100% coverage. According to the rubric, a baseline score of 4 is appropriate. The description adds no parameter information because none is 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?

The description clearly states it returns the WhatsApp connection status and lists specific fields (connected, retention, transcription, etc.). The verb 'Return' and resource 'WhatsApp connection status' are unambiguous. Among siblings like get_brief or get_image, this is uniquely about connection status, making it easy to distinguish.

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 when connection status is needed, but does not explicitly state when to use or when not to use, nor does it mention alternatives. For a simple status check with zero parameters, the context is clear enough for an agent to understand its purpose, 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?

No annotations are provided, so the description carries the full burden. It discloses that data comes from a local cache, is sorted by recency, and distinguishes between human-friendly name and internal id. It does not mention potential error states or performance, but is largely transparent about its 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, both informative and free of fluff. The first sentence states the purpose, and the second provides critical usage guidance on name vs id. 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?

Given the single undocumented parameter and no output schema, the description lacks completeness. It explains the chat fields but not the effect of excludeGroups, nor does it mention whether results are paginated or limited. With sibling tools that depend on this list, more detail would be beneficial.

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 one optional parameter (excludeGroups) with default false, but the description does not mention it at all. With 0% schema description coverage, the description should compensate by explaining this parameter's meaning, but it fails to do so.

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 lists WhatsApp chats from the local cache sorted by most recent activity. It distinguishes itself from sibling tools (e.g., get_recent_messages) by focusing on chats, not messages or media, and adds clarity by explaining name vs id fields.

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 guidance on how to present chat names to users (use name, hide id), but does not explicitly state when to use this tool versus alternatives. It implies it's the first step for chat-related operations, but lacks explicit when-not or alternative references.

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 provided, so description fully carries burden. It declares read-only, no download/write, and lists return fields including likelyExpired meaning. Covers essential behavioral traits.

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 plus example, no fluff. Purpose stated upfront, efficient use of text.

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 5 parameters, no output schema, and no annotations, description should provide more parameter context. It covers return fields and usage well but misses parameter details, leaving agent to guess or rely on sibling tool 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?

Schema coverage is 40% (only kinds and chatId described). Description does not explain hours, limit, excludeGroups parameters, nor their role in previewing. Users cannot infer parameter semantics from text.

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?

Description clearly states it previews items for save_media_window, with specific verb 'Preview', resource 'media window', and notes read-only nature. Distinguishes from sibling save_media_window.

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 instructs to use BEFORE save_media_window and gives a concrete user-facing example. No exclusions needed.

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 discloses credential deletion and cache preservation, but does not fully describe side effects (e.g., service interruption until re-link) or auth requirements. It is adequate but not thorough.

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 wasted words. First sentence states purpose, second sentence details output and usage. Perfectly 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?

Given the tool's simplicity (1 optional param, no output schema, no annotations), the description covers operation and user instructions well. Missing only explanation of 'waitMs' and explicit relation to siblings. Nearly complete.

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

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

The schema has 0% description coverage and one optional parameter 'waitMs' (default 25000). The description does not explain this parameter at all, leaving the agent to guess its purpose (likely QR wait time). This is a significant gap.

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

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

The description clearly states the tool's purpose: 'Delete stale credentials and start a fresh QR pair.' It uses specific verbs ('delete', 'start') and resources ('credentials', 'QR pair'), and distinguishes from siblings like 'wait_for_link' which handles the subsequent step.

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 credentials are stale and need refreshing. It provides explicit instructions for rendering the QR and user action. However, it does not explicitly state when not to use it or mention alternatives beyond the implied sibling 'wait_for_link'.

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. It discloses the saving action and enumerates failure codes (not_found, not_image, etc.), aiding understanding. However, it does not explicitly mention side effects like overwriting or atomicity.

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 paragraph. It begins with the core purpose, then details input sources, naming convention, return format, and failure codes. Every sentence adds value, with no 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 tool with 6 parameters and no output schema or annotations, the description covers essential aspects: purpose, input requirements, storage location, naming, and failure modes. It lacks explicit success response structure, but the resource_link return is implied. Overall, it is fairly 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 67% (4 of 6 params described). The description adds meaning beyond schema by explaining the source of chatId/msgId (from get_recent_messages), default folder format, and naming convention. For parameters like timeoutMs and skipIfExists, it provides defaults not in schema.

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

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

The description clearly states 'Save a single WhatsApp image to disk', specifying the action (save) and resource (WhatsApp image). It distinguishes from siblings like 'save_media' (general media) and 'save_voice' (voice messages) by being image-specific.

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 instructs to 'Pass the chatId + msgId from a get_recent_messages result', providing clear context on when to use the tool. It does not explicitly state when not to use it or list alternatives, but the usage context is clear.

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

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

No annotations provided, so description bears full burden. It only says 'save-to-disk' without disclosing side effects (e.g., overwriting, disk space), permissions, rate limits, or error states. The skipIfExists parameter suggests idempotency, but description does not elaborate.

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 sentences, front-loaded with purpose and usage guidance. No wasted words, though it omits parameter information. Concise but incomplete.

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?

Tool has 6 parameters and no output schema, yet description covers only high-level purpose. Lacks information on return values, error handling, or parameter constraints. Incomplete for the tool's 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 0%, yet description adds no parameter details. It does not explain msgId, chatId, folder, filename, timeoutMs, or skipIfExists. Agent cannot infer parameter meaning from description alone.

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?

Description clearly states it's a generic save-to-disk for any media kind (image/audio/video/document). It distinguishes from siblings by naming save_image and save_voice as type-specific alternatives, making the tool's purpose and unique role clear.

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 advises using specific tools (save_image, save_voice) when the type is known for clarity, and recommends this tool for mixed lists of msgIds to avoid branching. Provides clear context and exclusion criteria.

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 discloses behavior: concurrency, per-item success/failure, abort conditions only on disk_full/disconnect, default folder, error reporting structure. This is comprehensive and leaves no ambiguity about tool 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 a single, dense paragraph with no wasted words. Each sentence adds value: purpose, behavior, failure handling, folder path, abort conditions. Front-loaded with main action.

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 10 parameters, no annotations, and no output schema, the description is remarkably complete. It explains the return format (items[], errors array, ok status), default folder, concurrency, and error handling. Only minor details like per-parameter defaults are left to the 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?

Schema description coverage is 50%. The description adds context (e.g., 'bounded concurrency (default 3)', 'per-item results') but does not fully compensate for undocumented parameters like excludeGroups and hours. Baseline 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 starts with a clear verb and resource: 'Bulk-save WhatsApp media from the last N hours to disk.' It distinguishes from sibling tools like save_image or save_voice by specifying bulk and time-window operation.

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 behavioral details but does not explicitly state when to use this tool versus alternatives like save_image or list_media_window. Usage context is implied but not directly contrasted with 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?

With no annotations, the description takes on full burden. It discloses that the tool saves to disk, optionally transcribes (requiring OpenAI API key), returns transcript inline, and lists error codes. Missing details on failure handling or overwrite behavior, but overall transparent.

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 (4 sentences) and front-loads the core purpose. It is efficient but could be slightly more structured, though it remains easy to read.

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 7 parameters, no output schema, and no annotations, the description covers purpose, optional transcription, and error codes, but lacks details on return values beyond transcript inline and does not provide example usage. It is adequate but leaves gaps for an AI agent.

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 low (29% - only timeoutMs and transcribe have descriptions). The description adds meaning by mentioning transcribe:true and the same parameter contract as save_image, but does not explain chatId, msgId, folder, filename, or skipIfExists beyond the schema. Reliance on another tool's description is insufficient.

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 saves voice notes (.ogg) to disk and optionally transcribes them. It references save_image as a similar tool, helping differentiate from image saving but not from save_media or other 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 implies usage for voice notes and when transcription is needed, but does not explicitly state when not to use it or recommend alternatives. The reference to save_image provides some context but lacks clear when-to or when-not-to 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?

No annotations are provided, so the description carries the full burden. It discloses case-insensitivity, the configurable time window, output formatting (human-friendly names), and a critical usage warning about raw IDs. It implicitly indicates a read-only operation.

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 three sentences with no redundant information. The first sentence states the purpose, the second adds a key parameter detail, and the third provides output format and a critical usage rule. 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?

Given no output schema or annotations, the description covers purpose, time window, and output format. However, it does not explain the remaining parameters (limit, excludeGroups), the exact return structure, or behavior when no results are found.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only explains the 'hours' parameter with its default and meaning. 'query', 'limit', and 'excludeGroups' are not mentioned, leaving significant gaps for the agent.

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 performs a case-insensitive substring search across cached messages. This specific verb+resource pairing distinguishes it from sibling tools like get_recent_messages, which retrieves without search.

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 searching messages with constraints (time window, human-friendly output) but does not explicitly state when to use this tool over alternatives or provide exclusions. The imperative note about never showing raw IDs gives some 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 should disclose behavioral traits. It states it writes to a file, but does not specify whether it overwrites, appends, or handles errors. No mention of auth, side effects, or file creation 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 short sentences, front-loaded with the action, no unnecessary words. Every sentence serves a 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?

For a simple 1-parameter tool, the description covers purpose and basic context but lacks details on behavior (e.g., overwrite policy) and return value, leaving gaps for a complete understanding.

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 coverage is 0%, yet the description only mentions 'JSON brief object' without explaining the structure or required fields shown in the schema. It adds minimal value beyond the parameter name.

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 explicitly states 'Write a JSON brief object to data/brief.json', clearly identifying the verb (write) and resource (brief object to a file). It also distinguishes the tool from siblings like get_brief by specifying it is called after analysis for rendering.

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 says 'Called by Claude after analyzing messages', providing context for when to use. However, it does not explicitly exclude use in other cases or mention alternatives like get_brief for reading.

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 discloses behavioral traits: it is a write operation that saves to cache, reduces vision token usage, and future briefs reuse the description. It doesn't fully cover idempotency or overwrite behavior, but provides valuable context.

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 main action, and contains no wasted words. It is efficiently 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 covers the workflow, parameters, and rationale. It could be more explicit about the association between chatId/msgId and the image, but is mostly complete for a simple write 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?

The description only clarifies the description parameter's ideal length (1-2 sentences), but does not explain chatId and msgId. With 0% schema coverage, more parameter guidance is 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?

The description clearly states the tool's purpose with a specific verb ('save') and resource ('description back to the cache'), and places it in the workflow after get_image, distinguishing it from siblings like set_brief.

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 tells the agent to use this tool after get_image and explains the benefit of caching. It also prescribes the description length (1-2 sentences). However, it doesn't mention alternatives or when not to use it, so it's not a 5.

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 bears the full burden. It mentions blocking behavior and timeout but lacks details on side effects, error handling, or whether it's safe to call multiple times. Adequate but not thorough.

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, concise and front-loaded. Every sentence adds value.

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 (one optional parameter, no output schema), the description is complete. It covers purpose, usage, and parameter role.

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

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

Schema description coverage is 0%, so the description must add value. It mentions timeout generally but doesn't explicitly explain that waitMs is the timeout duration. The parameter name is self-explanatory, so baseline 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 it blocks until a WhatsApp connection event or timeout, and it explicitly mentions its role after relink_whatsapp. It distinguishes itself from sibling tools by being a blocking/confirmation 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?

The description explicitly says 'Use after relink_whatsapp to confirm the user scanned successfully,' providing clear context and a specific use case. It does not list when not to use it, but the 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 describes the output (folder path and file count) and implies a read-only query. It's transparent about what the tool does.

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 purpose, no unnecessary words. Efficient and clear.

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 query tool with no output schema, the description covers the key outputs and use case completely.

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?

No parameters exist, so baseline 4 applies. The description adds no parameter information, which is fine since there are none.

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 returns the default folder for media saving operations (save_image, save_voice, save_media_window) along with file count, and distinguishes from siblings by being a query rather than a write operation.

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 says 'useful for answering "where did you save them?"', providing clear context. It doesn't list exclusions, but the purpose is straightforward.

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