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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the repeated "Read-only with no side effects" adds little. The description does add meaningful behavior by explaining the ranking and the computed fields (last message date, last reply date, unanswered inbound count), though it leaves sorting tie behavior and pagination unstated.

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 short and front-loaded: it states the primary purpose first, then the safety profile and usage guidance. Every sentence contributes to selection or interpretation.

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 fully described parameter, and an output schema present, the description need not explain return values in detail. It still provides enough purpose, usage, and behavioral context for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, and the single limit parameter is already fully documented in the schema. The description does not add syntax or filtering semantics for limit, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb and resource ("List Signal chats") and adds the ranking criterion (recent activity) plus the fields surfaced. It explicitly distinguishes itself from list_chats, so an agent can select 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?

It states the intended use case ("identify chats that need a response") and names the alternative (list_chats) with the condition that selects it (general chat directory with message previews). This is explicit when-to-use guidance.

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

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

Goes well beyond the annotations: it discloses that it is read-only on Signal data but writes a decrypted copy to a temp directory that is not auto-cleaned, and enumerates failure modes (missing file, wrong key length, HMAC mismatch) with the 'Error:' prefix convention. This is exactly the side-effect and auth/state context an agent needs before calling.

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 is front-loaded in the first clause and each sentence carries operational content. The return-value explanation is somewhat redundant given an output schema exists, which slightly blunts conciseness.

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?

Covers source of inputs, side effects, cleanup caveats, and error surface, which is everything needed for a two-parameter cryptographic tool with an output schema and annotations already present.

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 provenance ('attachment metadata in read_messages or search_messages results') that tells the agent where to obtain the values. It does not restate format details, which the schema already covers well.

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 ('Decrypt a locally stored Signal attachment') plus the outcome ('return the path to the decrypted file'). This is clearly distinct from the reading/searching siblings that merely surface the metadata this tool consumes.

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 routes the agent: values 'come from attachment metadata in read_messages or search_messages results' and 'Use this after reading messages that contain attachments.' It gives clear positive conditions but no explicit when-not-to-use or alternate tool.

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' adds little beyond structured data. However, the description does add real value by tying the check to a pre-flight workflow and by naming the configuration conditions (source dir, CLI availability, account configuration) that gate later operations.

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 core check, then the return shape, then the routing guidance — a sensible order with no filler. Slight redundancy in listing the five boolean field names when an output schema already exists, but it is compact enough not to be a real cost.

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, read-only status probe with full annotation coverage and an output schema, the description covers purpose, preconditions, return semantics and the sibling alternative. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly spends no space on parameter semantics.

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

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

The description names a specific check ('whether the Signal MCP server can read local messages and send outbound messages') rather than restating the name, and it enumerates the exact boolean fields returned. It is clearly distinguishable from siblings like pairing_status and read_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?

Explicit when-to-use ('call this before read or send operations to verify configuration') and an explicit alternative with its condition ('call pairing_status instead to check first-run device-linking state'). An agent has no inference left to make about tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so 'Read-only with no side effects' is largely redundant. The description does add non-annotation context: the data source (local desktop database) and the result ordering (most recent message first), which affects how an agent interprets results. No auth or pagination caveats, but nothing contradicts annotations.

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 core action and scope, followed by return contents and sibling routing. Efficient overall, though 'Read-only with no side effects' duplicates the annotation block and doesn't add signal.

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?

Output schema exists so return values needn't be described, annotations cover the safety profile, and schema fully documents both parameters. The description contributes the remaining needs: data source, sort order, and sibling routing. Nothing an agent needs 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?

Schema coverage is 100% with defaults and ranges documented for both limit and query, so the schema already does the work. The description mentions no parameter behavior at all (e.g., how limit interacts with sorting, or whether query matches phone numbers), so the baseline of 3 is right.

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 from the local desktop database') with scope qualifiers: local database, sorted by most recent message. Clearly separable from list_groups, which it names as a different scope.

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 ('discover exact chat names before calling read_messages or search_messages') and an explicit when-to-use-alternative ('Use list_groups instead when you need group_id values for send_message'). This routes the agent between siblings with no inference required.

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 behavior beyond the annotations: a dual data source with a degraded fallback ("falls back to the local desktop database (without group_id)"), which is correctness-critical since the group_id may be absent. The safety profile is only restated from annotations ("Read-only with no side effects") and there is no mention of latency, rate limits, or whether the fallback is surfaced in the result, keeping it short of 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?

Front-loaded with the resource and return fields, then source caveat, then routing guidance — a sensible information hierarchy with no filler. The "Read-only with no side effects" sentence largely duplicates the annotations and could be dropped.

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 no explanation, yet the description still names the key fields and their ordering. Combined with the fallback caveat and the sibling routing note, an agent has everything needed to call this 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 description coverage is 100%, with both limit (range 1-200, default 50) and query (case-insensitive substring, empty returns all) fully documented in the schema. The description says nothing extra about filtering or pagination, so it meets but does not exceed the baseline for a fully documented 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 ("List Signal groups") and enumerates the returned fields (group_id, name, description, members, admin lists) plus the sort order. It also explicitly distinguishes itself from list_chats, so an agent can pick between them 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 a concrete downstream use ("obtain group_id values needed by send_message") and names the alternative with the condition that selects it ("Use list_chats instead for a combined view of both direct and group chats"). Both when-to-use and when-to-use-something-else are covered.

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=false and idempotentHint=false but never explain why; the description supplies the reason — the first call on an unlinked device spawns a background signal-cli link process as a side effect. It also details the three state outcomes and the expected empty qr_payload on the first call, which no structured field conveys.

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 is front-loaded in the first sentence, then the return states, then the side-effect caveat, then the sibling routing — a sensible information order. The line-wrapped prose and heavier detail on the envelope make it longer than strictly necessary.

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?

Covers the three possible states, the expected empty first-call payload, the background process side effect, and the handoff to get_status — everything an agent needs to call and interpret this 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?

Zero parameters, so the baseline is 4. The description compensates by documenting the return envelope (ready/awaiting_qr/error, qr_payload) even though an output schema exists.

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') plus the caller-facing goal (surface the live link QR). It explicitly routes the agent away from get_status once linked, so it is distinguishable from siblings 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?

Gives explicit when-to-use ('Poll this to drive a pairing UI'), when-not ('call get_status instead to check read/send availability once linked'), and the polling cadence implied by the awaiting_qr flow. Nothing is left for the agent to infer.

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 readOnly/idempotent/non-destructive, so the 'read-only with no side effects' sentence is largely redundant, but it does not contradict them. The description adds real behavioral value beyond annotations: messages come back newest-first, and each item carries sender, date, body, reactions and attachment metadata. It omits pagination/limit behavior, which keeps it from 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?

Four short sentences, front-loaded with what the tool returns and in what order, then contents, safety, prerequisite, and alternative. 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?

Output schema exists, schema coverage is complete, and annotations cover the safety profile, so the description only needs orientation — which it provides (ordering, contents, prerequisite, alternative). Slight gap: no mention that results are paginated via limit/offset, though the schema covers it.

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

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

Schema description coverage is 100%, so after/before/limit/offset/chat_name are already fully documented in the schema. The description only reinforces the case-sensitivity prerequisite for chat_name and adds nothing about the time-window or pagination parameters, 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 specific verb and resource (read messages from a single Signal chat) plus an important scope detail: returned newest-first. It explicitly distinguishes itself from both list_chats (name source) and search_messages (keyword search across chats), so an agent can pick it without reading schemas.

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 a prerequisite (exact chat name from list_chats) and a named alternative with the condition that selects it ('Use search_messages instead to find messages by keyword across chats'). Both when-to-use and when-not-to-use are covered.

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 readOnly, idempotent, and non-destructive, so the 'Read-only with no side effects' sentence adds nothing new. However the description does add genuinely non-annotated behavior: newest-first ordering, the per-chat vs. global scope, and the exact result fields (sender, date, chat name, body, reactions, attachment metadata). Pagination behavior is still unstated, keeping it below 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?

Front-loaded with the core action and scope, then results, then routing. Nearly every sentence earns its place, though 'Read-only with no side effects' duplicates the annotations and could be dropped.

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 explained, yet the description still summarizes them usefully. Scope, ordering, and sibling routing are all present; nothing an agent needs 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 are fully documented in the schema, including case-insensitivity and the 1-200 range. The description only restates the chat-vs-all scope and adds no format or syntax detail beyond the schema; 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 ('Search Signal message bodies'), the searchable scope (one chat or all chats), and the ordering (newest-first). It explicitly contrasts itself with read_messages, so an agent can distinguish 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?

Gives explicit selection criteria: 'Use this to find messages by content. Use read_messages instead to browse a specific chat chronologically.' The alternative and the condition that selects it are both 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). It discloses irreversibility ('Sends are not reversible from this server'), that deletion is only via official clients, concrete rate limits (1 per recipient per second, 10 per 60s globally), the external dependency on signal-cli/SIGNAL_ACCOUNT, and the success return fields.

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 the one-line purpose, then layers constraints, rate limits, prerequisites, and return info in short discrete sentences. It is longer than minimal but every sentence carries a distinct operational fact; only minor trimming is possible.

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, yet the description still name-checks the success payload (target_type, target identifier, timestamp). Combined with constraints, rate limits, and prerequisites, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% so baseline is 3, but the description adds the crucial exactly-one-recipient rule and states that zero or more than one raises an error — stricter information than the schema's 'mutually exclusive' notes and not derivable from the required list (only message is required).

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

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

States a specific verb and resource (send a text message via Signal) plus the two target types (direct recipient or group). This clearly separates it from read_messages, search_messages, and chat_activity among the 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?

Gives an explicit prerequisite: signal-cli and SIGNAL_ACCOUNT must be configured, and the agent should call get_status first to verify send_available is true. It does not explicitly name alternative send paths or exclusion cases, but the precondition guidance is concrete and actionable.

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