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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so 'Read-only with no side effects' restates structured data rather than adding to it. The ranking/derived-metric behavior is useful context, but no new behavioral traits (ordering guarantees, staleness, empty-result behavior) are disclosed beyond what annotations provide.

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 blocks, front-loaded with the purpose and followed by routing guidance; nothing is bloated. The only minor waste is the read-only sentence, which duplicates the annotations and could be dropped 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?

An output schema exists, so return values need not be re-explained, and the description covers purpose, ranking semantics, usage intent, and the sibling alternative. For a single-optional-parameter read tool, nothing an agent needs 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% and the single limit parameter is fully documented with range and default in the schema. The description contributes no additional meaning about pagination, defaulting, or how limit interacts with ranking, 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?

The description gives a specific verb (List), resource (Signal chats), and scope (ranked by recent activity), plus the exact fields surfaced: last message date, last reply date, and count of unanswered inbound messages. It also explicitly distinguishes itself from list_chats, which allows an agent to route correctly without inspecting either schema.

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 states the intended task ('Use this to identify chats that need a response') and names the alternative plus the condition that selects it ('Use list_chats instead for a general chat directory with message previews'). Both the when-to-use and the when-to-use-something-else paths are explicit.

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?

Adds substantial context beyond the annotations: it writes a decrypted copy to a temp directory that is NOT auto-cleaned, is read-only on Signal data, and returns either an absolute path or an 'Error:'-prefixed string for the three specific failure modes (missing file, wrong key length, HMAC mismatch). This is exactly the state-changing side effect the annotations (readOnlyHint=false) imply but do not explain.

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?

Front-loads what it does and how to use it, then covers side effects and error format. Five sentences with no filler, though the parameter-provenance sentence slightly overlaps the schema descriptions.

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?

Despite an output schema existing, the description still usefully documents the success/error string contract and the non-auto-cleaned temp file. Combined with full parameter coverage and clear invocation context, nothing an agent needs to call this safely 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 coverage is 100% so the parameter formats are documented, but the description adds provenance — both values come from attachment metadata in read_messages or search_messages results — which tells the agent where to source valid inputs. That is marginal value beyond the schema, above 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?

States a specific verb (Decrypt) and resource (locally stored Signal attachment) plus the return value (path to the decrypted file). No sibling tool does anything similar, so the agent can distinguish it immediately.

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 'Use this after reading messages that contain attachments' and identifies that encrypted_path and local_key come from read_messages or search_messages results, giving clear context. It does not, however, state any when-not condition or name alternatives for the case where decryption fails.

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, idempotentHint and destructiveHint=false, so 'Read-only with no side effects' is largely redundant. However, the description adds real context by enumerating the capability checks performed (source dir, CLI availability, account configured, read/send availability), which tells the agent what a successful verification actually confirms.

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?

Front-loaded with the purpose, then usage routing, then return fields — a sensible order. It is slightly padded: the return-field list duplicates the output schema and 'Read-only with no side effects' duplicates the annotations.

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 zero params, rich annotations, and an output schema documenting the boolean return values, the description covers purpose, usage routing, and safety profile. Nothing an agent needs in order to call 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?

Zero parameters, so the baseline is 4. The description adds no parameter detail, but none is needed since the input schema is an empty object with additionalProperties=false.

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+resource: checking whether the Signal MCP server can read local messages and send outbound messages. It explicitly names the sibling it is not (pairing_status), so an agent can distinguish it without opening the schema.

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?

Gives explicit when-to-use ('Call this before read or send operations to verify configuration') and a when-to-use-the-alternative rule ('call pairing_status instead to check first-run device-linking state'). Nothing is left to inference.

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, idempotentHint, non-destructive, and closed-world, so 'Read-only with no side effects' is largely redundant. However, the description adds behavior the annotations do not: the sort order (most recent message) and the local-database scope, which help predict results.

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?

Purpose and sort order are front-loaded, followed by result fields and routing guidance; every sentence contributes. The 'Read-only with no side effects' clause is redundant with the annotations and is the one phrase that does not earn 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?

With rich annotations, a 100%-covered input schema, and an output schema handling return values, the description covers everything an agent needs: what is returned, ordering, safety, and which sibling to prefer. No material gap remains.

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 limit and query are already fully documented with defaults and ranges. The description adds no parameter-level detail (e.g., filtering semantics or pagination interaction) 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 ('List direct and group Signal chats'), names the data source ('local desktop database'), and the ordering ('sorted by most recent message'). It also distinguishes itself from the list_groups sibling, so an agent can select it without opening any schema.

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 downstream use case ('discover exact chat names before calling read_messages or search_messages') and the exclusion ('Use list_groups instead when you need group_id values for send_message'). Both when-to-use and the alternative tool are spelled out.

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, idempotentHint and destructiveHint=false, so the description correctly adds value beyond them by disclosing the data source: signal-cli when available, with a fallback to the local desktop database that omits group_id. That degradation caveat is real behavioral context an agent must know. It stops short of detailing result shape, but an output schema exists to carry that.

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 core verb and resource lead, followed by behavior, then routing. Every sentence carries a distinct load – fields, safety, data source, and two sibling disambiguations – with no padding.

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 filtered, read-only list tool this is complete: it covers purpose, safety, data-source fallback behavior, pagination-adjacent filtering via schema, and routing to the correct sibling. The existence of an output schema means return values need not be explained here.

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 limit and query are fully documented in the schema already. The description adds no syntax or format detail for either parameter, making the baseline 3 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?

States a specific verb and resource ("List Signal groups") and enumerates the returned fields (group_id, name, description, members, admin lists) plus sort order. It explicitly distinguishes itself from the sibling list_chats, so an agent can tell the two apart without opening either schema.

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?

Gives two explicit routing rules: use this to obtain group_id values needed by send_message, and use list_chats instead for a combined direct+group view. Both the when-to-use and the alternative are named, leaving nothing to inference.

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 a non-obvious side effect beyond the annotations: the first call on an unlinked device starts a background signal-cli link process, and the first call may return 'awaiting_qr' with no payload yet. This complements the readOnlyHint=false / idempotentHint=false annotations with concrete behavioral detail about the state machine and error condition.

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?

Front-loaded with purpose, then the return envelope, then the side-effect caveat and the sibling routing. Dense but every sentence carries operational value; the state-by-state enumeration is slightly verbose but justified for a polling contract.

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 zero-parameter polling tool, it covers the states ('ready', 'awaiting_qr', 'error'), the payload format, the first-call edge case, and the sibling alternative. Although an output schema exists, the inline state description is consistent and leaves no gap an agent needs 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?

The tool takes no parameters, so the baseline is 4; there is nothing to document and nothing to mislead. The description's envelope details are about returns, not parameters.

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 ('Report the Signal device-linking setup state for first-run pairing') and scopes it to a QR-surfacing client use case. It clearly distinguishes itself from the sibling get_status by framing this as the pairing-flow 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 says to poll this to drive a pairing UI, and names the alternative ('call get_status instead to check read/send availability once linked') with the condition that selects it. When-to-use and when-to-switch are both stated.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the description's 'Read-only with no side effects' mostly reinforces known safety. It adds useful non-annotation behavior: results are newest-first and each message includes reactions and attachment metadata. Auth needs, rate limits, and pagination behavior are not described.

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 core action and ordering, then covers return contents, safety, prerequisite, and alternative routing in four tight sentences. No sentence is wasted or redundant enough to impede scanning.

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 output schema exists, annotations cover safety and idempotency, and schema coverage is complete, the description supplies exactly the missing contextual pieces: scope, ordering, required input provenance, and sibling routing. An agent has enough information to select and invoke the tool correctly without needing return-value details in prose.

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 fully documents all five parameters, including datetime formats, limit range, and pagination offset. The description adds little beyond restating that chat_name must be exact and come from list_chats, which the schema also states.

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 states a specific verb and resource ('Read messages from a single Signal chat'), specifies the order ('newest-first'), and names the sibling alternative search_messages. An agent can distinguish this tool from list_chats, search_messages, chat_activity, and send_message without opening the schema.

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 states the prerequisite ('Requires an exact chat name from list_chats') and gives a clear alternative condition ('Use search_messages instead to find messages by keyword across chats'). This tells the agent when to use this tool versus a sibling that could otherwise seem overlapping.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so 'read-only with no side effects' largely restates structured data. The description does add ordering (newest-first) and the shape of each result, though the result-field list overlaps with the output schema. Useful but partly redundant.

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?

Front-loaded with purpose and scope, then usage routing, then return shape. Efficient overall, though the enumerated result fields are somewhat redundant given the output schema is declared.

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 full annotations, 100% schema coverage, and an output schema that covers return values, the description's remaining duty is scope, ordering and sibling routing, all of which are present. Nothing needed to invoke the tool 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 query, limit and chat_name semantics (substring matching, 1-200 bound, omit-to-search-all) are already documented. The description only restates the one-chat-vs-all-chats scoping that chat_name already encodes, adding no syntax or format detail 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?

Specific verb (search) plus resource (Signal message bodies), stated scope (one chat or all chats), and result ordering (newest-first). It explicitly distinguishes itself from read_messages, so an agent can route between the two without opening either schema.

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?

States the selection condition ('find messages by content') and names the alternative with its own condition ('read_messages instead to browse a specific chat chronologically'). This is explicit when-to-use and when-not-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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses that sends are irreversible from this server, the exact rate limits (1/recipient/second, 10 per 60s global), the external dependency on signal-cli plus SIGNAL_ACCOUNT, and the success return fields. This is exactly the kind of context a write tool needs.

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?

Front-loaded with the action, then constraints, prerequisites, and return value in a tight sequence with no filler sentences. Every sentence carries operational 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 four-parameter write tool, the description covers target selection, irreversibility, rate limits, configuration prerequisites, and result fields. With an output schema present, it need not detail return contents further, so nothing material 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 coverage is 100%, so the baseline is 3, but the description adds error semantics not present in the schema: supplying zero or more than one recipient field raises an error, making the exactly-one constraint explicit rather than merely mutual exclusivity.

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 first sentence gives a specific verb (send), resource (text message), transport (Signal), and both supported target modes (direct recipient or group). This is unambiguous against siblings like read_messages, search_messages, and list_chats, which are all read/list operations.

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

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

It states a concrete prerequisite (call get_status first to verify send_available is true) and the target-selection rule that exactly one of phone_number/group_id/chat_name must be set. It does not name alternatives for non-send cases or say when not to use this tool, so it stops short of the top tier.

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