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

Annotations only declare the generic safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false). The description adds what annotations cannot: the exact error string returned when run on a linked device, the three failure modes, the fact that the linked device gains full account access, and an explicit security warning never to use an untrusted URI.

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 prerequisites, failure modes, and cleanup path in a tight sequence; every sentence carries operational information. It is on the denser side for a one-parameter tool, but no sentence is filler.

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

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

For a single-parameter, no-output-schema mutation tool, it covers everything an agent needs: prerequisite state, error conditions, security caveat, the return status string ('device linked'), and the follow-up/undo tools.

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

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

Schema coverage is 100% and the single uri parameter is fully described in the schema, so the description's mention of 'the device-link URI (sgnl://linkdevice?...) shown as a QR code or printed by signal-cli link' mostly reinforces existing schema text. Baseline 3 applies when the schema carries the 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?

States a specific verb and resource — 'Link a new device ... to your account' — with an example of what a device is. It is immediately distinguishable from siblings like list_devices, update_device, and remove_device.

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

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

Explicitly states the precondition (only works when signal-mcp is the primary device), the failure conditions (linked-device setup, malformed/expired link, device limit), and routes the agent to alternatives: confirm with list_devices, undo with remove_device.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), but the description adds concrete meaning: the exact return shape {status: 'installed', pack_id}, that pack_id is parsed from the uri, and that re-installation is a no-op. It stops short of mentioning any auth or rate-limit considerations, but the added behavioral context is real.

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, then the input constraint, then the return value and routing. Every sentence carries information, though the inline uri format with angle-bracket placeholders makes the middle clause slightly dense.

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

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

With no output schema, the description compensates by documenting the return payload and the parsed pack_id, and it names the downstream tools (send_sticker, send_group_sticker, get_sticker) plus the inspection tool (list_sticker_packs). Nothing needed to invoke this 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 a single uri parameter, but the description goes beyond the schema by spelling out the required fragment structure (pack_id=<hex>&pack_key=<hex>) and stressing that both pack_id and pack_key must be present — a validation detail the schema's terse description does not convey.

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 ('Install') plus resource ('an existing sticker pack on this Signal account') and the required input format (signal.art link). It also explicitly distinguishes itself from upload_sticker_pack, which publishes new packs, so an agent can disambiguate without reading 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 the when (install an existing pack via signal.art uri), the when-not/alternative (use upload_sticker_pack to publish your own images), and the repeat-call behavior (installing the same pack again has no further effect). It also routes to list_sticker_packs for inspecting pack contents.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds context annotations cannot express: 'Irreversible; contacts Signal's servers; the local store copy is kept.' That local-store nuance is non-obvious and material to the caller's decision.

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, followed by alternatives, prerequisites, and parameter sourcing in tight clauses. Every sentence carries operational value with no filler.

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

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

Even without an output schema, the description documents the return shape (returns {status: 'message deleted by admin'}), the permissions requirement, the server/local split, and sibling routing. 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 coverage is 100%, so the baseline is 3, but the description adds format detail beyond the schema — E.164 numbering for target_author and that target_timestamp is the message id 'in ms' from get_conversation. These sharpen how to supply the values.

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 ('delete'), resource ('any member's message'), and scope ('in that group for all participants'), and explicitly distinguishes itself from delete_group_message, delete_message, and delete_local_messages. An agent can identify this tool without opening any sibling 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?

Names each alternative and the condition that selects it (own messages vs. member messages, group vs. DM, server vs. local removal), and states the prerequisite plus how to verify it ('check is_admin in list_groups'). This is explicit when-to-use/when-not 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?

Annotations only say destructiveHint=false and idempotentHint=true; the description adds substantial context beyond them: the primary-device precondition and error string, that the contact is not notified, that the blocked list syncs to linked devices, that the profile key is rotated when no shared group exists, that message history is kept, and that re-blocking is a no-op (consistent with idempotentHint).

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 constraints, side effects and the alternative tool. Despite being a dense paragraph, every sentence carries distinct, decision-relevant information and none is filler.

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

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

With no output schema, the description compensates by stating the return value ('status \'blocked\' and number'). Combined with preconditions, side effects, reversibility and the no-op case, 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% and the single parameter already documents E.164 format with an example. The description restates 'number (required, E.164)' but adds no new syntax or constraint beyond the schema, so the baseline 3 applies.

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

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

The description leads with a specific verb and resource plus the user-visible effect: 'Block a contact so you stop receiving their messages and calls.' It clearly distinguishes itself from sibling tools it is often confused with (remove_contact deletes the local entry only; unblock_contact reverses this).

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-it-works precondition ('Only works when signal-mcp is the account's primary device'), the exact failure message on linked devices, and a named alternative ('To only delete the local contact entry without blocking, use remove_contact'). Reversibility with unblock_contact is also 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?

Goes well beyond the annotations by disclosing that the operation is local-only, that the job remains in the list with status 'cancelled', that it is irreversible without rescheduling, and that an error is returned when no pending job matches (already sent, failed, cancelled, or unknown). That is exactly the mutation/irreversibility context an agent 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?

One dense paragraph that front-loads the action and outcome, then layers id provenance, behavioral caveats, and return shape. No sentence is filler.

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

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

With annotations covering the safety profile (destructive, idempotent, non-read-only) and no output schema, the description supplies the missing return shape and failure modes. Nothing an agent needs to invoke this correctly is absent.

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 already 100%, so the baseline is 3, but the description adds value by naming both source tools for the id and tying id validity to the error case. It still does not clarify whether the id is globally unique or per-account, so it stops short of 5.

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 ('Cancel one pending scheduled message') plus the outcome ('so it will never be sent'), which cleanly separates it from siblings like delete_message, schedule_message, and run_scheduled_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?

Names the tools that produce the required id (schedule_message, list_scheduled_messages) and routes the agent away from re-activation ('cannot be re-activated; schedule it again instead'). It gives clear context but never states when this should be preferred over other message-removal tools such as delete_message.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: the confirm guard and its failure mode, the local-only blast radius (nothing removed from Signal, phone, or other devices), the fact that downloaded attachment files on disk survive, and irreversibility except via re-import. That is the extra behavioral context annotations cannot carry.

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 dense sentences, all front-loaded: what it destroys, the guard, the blast radius, the recovery path, the return shape. No filler and no repetition of the name.

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

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

For a one-parameter irreversible mutation with no output schema, the description supplies everything needed: destruction scope, safety gate, side-effect boundaries, reversibility, and even the return shape ({deleted: count, status: 'cleared'}). Nothing an agent needs before calling it 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% and the single parameter is self-documenting, so the baseline is 3. The description adds genuine meaning beyond the schema's 'Must be true to proceed' by specifying the semantics are exact — confirm must be exactly true, otherwise nothing is deleted and an error is returned.

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 (delete), resource (ALL messages and attachment records), and scope (signal-mcp's local database), with 'ALL' and 'local' doing real disambiguating work against siblings that also delete things. An agent can distinguish it from delete_local_messages, prune_store, and delete_message 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 routes the agent: delete_local_messages for a single conversation, prune_store for old messages only, delete_message for unsending in Signal. It also names the recovery path (import_desktop, re-receive). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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=false, idempotentHint=false and openWorldHint=true, but the description adds the concrete consequences: it contacts Signal's servers, notifies every member, creates a second group if called twice, and discloses the returned fields. It does not cover permission/admin-setup requirements or rate limits, so it stops short of a 5.

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

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

Front-loaded with the core action, then parameters, side effects, returns and alternatives in a compact sequence. It is dense with clauses but each sentence carries distinct information; no filler.

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

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

With no output schema, the description compensates by enumerating return fields (status, groupId, timestamp, per-member results). Combined with side effects, path constraints and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description earns more: it specifies members must be E.164 and that avatar must reside inside SIGNAL_MCP_SEND_ROOTS, a path constraint the schema does not state. It also clarifies how the returned groupId is reused as group_id.

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 ('Create a new Signal group') plus the implicit role ('with you as admin'). It names two sibling tools it is not (update_group, send_group_message), so an agent can distinguish 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 routes the agent: 'Use update_group to change an existing group and send_group_message to post in it.' The when-not condition is stated alongside the alternative, 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?

Goes well beyond the annotations: it warns that each call contacts Signal's servers, is not idempotent, shares a 20-sends-per-minute rate limit, and is not saved to the local store. It also discloses the return shape {status, timestamp} and how the timestamp keys vote_poll/terminate_poll.

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?

Dense but front-loaded, leading with the action before branching into usage and parameter rules. Every clause carries information, though the packed single-paragraph form is slightly heavy.

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 exists, but the description supplies the return shape and the identity key needed for follow-up calls. Combined with rich parameter and behavioral detail, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, yet the description adds real meaning: options must have at least 2 or it errors, multi_select=true enables multi-answer (default single), recipient must be E.164, group_id comes from list_groups, and supplying neither is an error. This compensates for constraints the schema cannot express.

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 ('Create a poll') plus its delivery scope ('send it to a contact or group'). It explicitly names the sibling tools vote_poll and terminate_poll, so an agent can distinguish the lifecycle stages without opening 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 explicit routing ('Use vote_poll to vote and terminate_poll to close it') and states the selection rule for recipient (DM) vs group_id (group), including that providing neither is an error. Edge conditions are surfaced rather than 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 flag destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: irreversibility, that older clients may silently ignore the delete, that repeating it has no further effect, and that the local store copy is retained. It also discloses the return shape ({status: 'deleted'}) since no output schema exists.

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, then routing, then parameter sourcing, then caveats and return value. Despite its length, every clause carries distinct information (version dependency, irreversibility, idempotency, local-copy retention) with no filler.

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

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

For a destructive mutation tool with no output schema, the description covers everything an agent needs: safety profile (already in annotations, reinforced here), irreversibility, client-compatibility caveat, idempotency, parameter provenance, and the return value. 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 provenance the schema lacks: group_id comes from list_groups, and target_timestamp is the ms timestamp of the caller's own message from send_group_message or get_conversation. That sourcing guidance exceeds what the terse schema descriptions ('Group ID', 'Timestamp of the message to delete') provide.

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 ('Remote-delete (unsend) a message you sent to a group') with precise scope ('removing it for all members on Signal 5.0+ clients'). It explicitly distinguishes itself from the three closest siblings (delete_message for DMs, admin_delete_message, delete_local_messages), so an agent can route correctly 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-this vs alternatives: 'Use delete_message for DMs; admin_delete_message to delete another member's message as admin; delete_local_messages for local-only removal.' The selection condition for each alternative is 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?

Annotations already flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds genuinely new context: nothing is unsent from Signal or removed from other devices, changes are irreversible locally, and the return shape is {deleted, status} with 0 when nothing matched. This goes well beyond the annotation surface.

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 recipient semantics, then local-only scope, then alternatives. Dense but every clause carries information; the parenthetical return note is slightly cramped but 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?

No output schema exists, yet the description supplies the return shape and the zero-match case, plus the destructive scope and alternatives. For a single-parameter destructive tool, nothing an agent needs 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 baseline is 3, but the description adds real meaning the schema lacks: recipient accepts E.164 phone number or group ID, and using your own number deletes only note-to-self messages. That special-case behavior is not in the schema.

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

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

States a precise verb+resource+scope: 'Delete the locally stored messages of one conversation from signal-mcp's database.' The 'locally stored' qualifier immediately distinguishes it from Signal-side deletions, and the sibling routing makes the boundary explicit.

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 three alternatives and the condition that selects each: clear_local_store to wipe everything, prune_store to drop by age, delete_message to unsend in Signal. Nothing is left to inference about when to reach for this 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 destructive=true and idempotent=true, but the description goes well beyond them: irreversible, older clients may silently ignore it, repeating has no further effect, and the local store copy is retained. These are non-obvious behavioral traits an agent needs before invoking.

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, then alternatives, then constraints, then return value. Dense but each clause carries information; the constraint list is slightly packed but nothing is redundant.

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

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

With no output schema, the description still reports the return shape ({status: 'deleted'}), covers irreversibility, idempotency, client-version caveats, and where to obtain the timestamp. Nothing needed 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%, so the baseline is 3, but the description adds real value: recipient is specified as an E.164 number and target_timestamp as a millisecond timestamp obtainable from the send_message result or get_conversation. That clarifies format and provenance beyond the schema's generic wording.

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 precise verb and resource ('Remote-delete (unsend) a message you sent to one contact') with explicit scope ('one contact'). It names the two sibling tools it is distinct from, so an agent can route correctly 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 routing rules: use delete_group_message for groups and delete_local_messages for local-only removal. It also states the precondition that only your own messages can be deleted, which is exactly the when/when-not guidance 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?

Goes well beyond annotations: recipients see an '(edited)' label, only text changes while attachments/quotes/reactions stay, only your own messages can be edited, the stored body is overwritten locally and the old text is not kept, and repeating the same edit has no further effect. These details are consistent with destructiveHint=true and idempotentHint=true rather than contradicting them.

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 core action and the '(edited)' consequence, then routes to alternatives before parameter details. It is dense and information-rich, though a couple of clauses (e.g. the returns note) could be tightened.

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 mutation tool with no output schema, it discloses the return shape ({status, target_timestamp}), the server round-trip, and the local-overwrite behavior. Combined with annotations covering the safety profile, 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 already 100%, so the baseline is 3, but the description adds real meaning: target_timestamp provenance ('from the send_* result or the message id in get_conversation'), the 'no formatting conversion' constraint on message, and the E.164 / list_groups sourcing for recipient and group_id.

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 with scope: 'Replace the text of a message you already sent (DM or group)'. It immediately distinguishes itself from send_message and delete_message, so an agent can pick 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?

Explicitly names the situations to use it ('fix typos or update information') and the alternatives with their selection conditions: delete_message / delete_group_message to retract, and send a new message to reach different people. 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 readOnly/idempotent/non-destructive, so the burden is lightened, and the description still adds real behavior: store-scoped data only, a prerequisite sync step, error on an invalid 'since', and the return shape {format, data}. It omits anything about volume/performance or limits on large exports, which keeps it short of a 5.

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

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

Front-loaded with purpose, then format, optional params, caveats, return shape, and the alternative tool — a logical order with no filler sentences. It is somewhat dense and re-explains parameter meanings already present in the schema, which costs a little economy.

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

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

With no output schema, the description compensates by naming the return object and describing the contents of each format, and it covers the prerequisite and error case. Minor gaps remain around export size/limits and whether CSV escaping is handled, but nothing essential for calling 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?

Despite 100% schema coverage, the description adds genuine semantics the schema lacks: what 'json' actually contains (full message objects with resolved sender_name/group_name, attachments, extras), the exact CSV column set, the E.164/group-ID constraint on recipient, an ISO 8601 example for since, and the invalid-value error behavior.

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+output form: export messages from signal-mcp's local store as a single JSON or CSV string. It immediately signals how it differs from read-oriented siblings by naming get_conversation and search_messages as the interactive alternatives.

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 clear context (archiving or analysis, bulk single-string output) and an explicit prerequisite: only messages already in the local store are included, so run sync_desktop or receive_messages first. It routes the agent to get_conversation/search_messages for interactive reading, though it never states an explicit 'do not use this for X' exclusion.

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, openWorldHint=false and destructiveHint=false. The description adds genuinely new context: that it reads the local contact store only, that the result may be empty, and it enumerates the returned fields — behavior not derivable from the annotations. It stops short of discussing pagination or ordering, so not 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?

Dense but front-loaded: the matching rule and the query semantics come first, then routing, then the return shape. Every sentence carries information, though the run-on construction makes it slightly heavier than it needs to be.

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

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

With no output schema, the description compensates by enumerating the returned contact object fields and noting the list may be empty. Combined with the sibling routing and the local-store scope, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by stating query is required and case-insensitive, and by explaining what all_recipients=false means in practice (group members known only by profile name). That example adds real meaning beyond the schema's phrasing.

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 (find) and resource (contacts) plus the exact matching fields (number, name, given/family name, nickname, username) and match semantics (case-insensitive substring). It also names the sibling it is not (list_contacts), so an agent can distinguish it 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?

Explicitly states when to use it (resolve a name to an E.164 number before send_message, or verify a contact exists) and when to use the alternative instead (list_contacts for listing everyone or filtering by blocked status). Both the positive and negative routing conditions are given.

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

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

Annotations only supply generic hints (readOnlyHint=false, idempotentHint=false, openWorldHint=true). The description adds concrete behavior beyond them: primary-device-only restriction with the literal failure message, irreversibility ('cannot be undone except by another change-number round'), and error semantics for a wrong PIN ('fails with the number of tries remaining').

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 step-2 framing and prerequisite are front-loaded, and each sentence carries a distinct fact (prereq, params, device restriction, consequence, error behavior, return value). It is dense rather than padded, though the run-on single paragraph could be split for faster 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?

No output schema exists, yet the description documents the return value ({status: 'number changed', number}), the prerequisite, the side effect, and the failure modes. For a 3-param, irreversible multi-step tool this covers everything an agent needs before calling.

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 real meaning the schema lacks: 'number' must be the same value passed to start_change_number, and 'pin' is conditional on a Registration Lock being set. It stops short of adding format nuances beyond E.164, which the schema already 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?

States a specific verb (submits the verification code) plus the exact scope: it is step 2 of moving this Signal account to a new phone number. It explicitly positions itself relative to the sibling start_change_number ('Call start_change_number first'), so an agent can separate the two-step flow 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 an explicit prerequisite ('without it there is no code to verify') and names the alternative path for the optional PIN parameter ('needed only if one is set (see set_pin)'). It also states the when-not condition: primary device only, failing on linked signal-cli setups.

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 explains the local copy into ~/Downloads/signal-attachments, that only attachments signal-cli already downloaded are available, the exact 'Attachment not found' failure, and that nothing is sent to Signal. This reconciles readOnlyHint=false with destructiveHint=false and idempotentHint=true meaningfully.

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?

Dense but front-loaded: the action and the required parameter come first, then resolution behavior, then return shape, then routing to siblings. Slightly long, though nearly every sentence carries distinct operational detail.

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

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

With no output schema, the description compensates by enumerating the return object ({filename, path, size, modified}) and clarifying it returns metadata rather than file content. For a single-parameter, non-destructive read/copy tool this is 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 coverage is 100% so the baseline is 3, but the description adds real semantics: accepted formats (filename or signal-cli attachment id) and the security constraint that path components such as '../' are rejected. That is genuine information not present in the schema.

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

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

States a specific verb and resource ('Look up one received attachment and make sure it is saved locally'), and distinguishes itself from siblings by naming list_attachments as the source of the identifier and send_attachment/send_group_attachment as the senders. An agent can route correctly 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 clear context and an explicit alternative ('Use send_attachment or send_group_attachment to send a file') plus where the filename comes from (list_attachments or a message's attachments). It does not spell out when-not to use it for other attachment operations, so it falls just short of the top band.

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 readOnly/idempotent annotations, it discloses the source (copy signal-cli has stored), the return shape (identifier, base64, has_avatar), decode format, and the exact failure case 'Could not find avatar'. This is rich context that annotations alone would not 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?

The description is front-loaded with the core action and avoids filler. It is a dense single paragraph, but every sentence contributes useful information; minor structural improvement could make the return and failure details easier to scan.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly with identifier, base64, and has_avatar. It also covers the failure case, identifier types, and related update tools, making it complete for this one-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning: identifier is required, E.164 for contacts, group id from list_groups for groups, and anything not full E.164 is treated as a group id. That heuristic parsing rule goes beyond the schema description.

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: return a contact's or group's avatar image as base64. It distinguishes the contact vs. group identifier rules and names related setters (update_profile, update_group), so an agent can identify the tool 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 gives concrete identifier conditions and points to update_profile/update_group for setting avatars, which helps route the agent. It does not explicitly state when not to use this tool or name a retrieval alternative, so it has clear context but lacks full exclusion 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?

Annotations declare readOnlyHint=false and idempotentHint=true, which is the non-obvious part here. The description explains the side effect well (incoming messages marked read in the local store only, no receipt sent) and that no server call is made. However the marking-read behavior IS the reason readOnlyHint is false, so the description mostly elaborates a trait the annotations already signal, keeping this at a solid 3.

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 and every sentence carries information (alternatives, params, side effect, return shape). It is dense and reads as a single packed block, but nothing is redundant.

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

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

With no output schema, the description supplies the return shape (messages, total, has_more, limit, offset) and even timestamp/id semantics. Combined with full param and side-effect coverage, nothing needed 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%, so baseline is 3, but the description adds genuine meaning: recipient accepts E.164 or group_id, offset is described as 'skip the newest N for paging back', and since notes invalid values return an error. These add semantics beyond the schema 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?

States a specific verb+resource ('Read the message history of one conversation') with clear scope ('from the local store, no Signal server call'). It explicitly distinguishes itself from list_conversations, search_messages, and get_unread, so an agent can route 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?

Names three alternative siblings with the exact condition that selects each (find conversations vs. search across chats vs. only unread). It also documents when to use send_read_receipt instead of relying on this tool for read receipts.

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, and openWorld=false, so the safety profile is covered. The description still adds beyond that: it characterizes the operation as a purely local lookup with no network call and no daemon dependency, plus the value's format. It loses the top mark only because 'no side effects' restates destructiveHint=false.

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 answer, then format, then behavioral traits, then routing to siblings. Every clause (E.164 example, local-lookup guarantee, two use cases, one exclusion) earns its place with no filler.

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

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

For a no-parameter, no-output-schema tool, the description supplies the missing return contract itself ({number} in E.164), the operational cost model (local, no network), and sibling routing. Nothing an agent needs to invoke it correctly is absent.

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; per the baseline for 0-param tools this lands at 4. The description correctly adds no parameter noise and instead spends its words on the return value.

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 ('Return this server's own Signal account number') and pins the exact return format with an E.164 example. It explicitly distinguishes itself from the closest sibling, list_accounts, so an agent can tell them 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?

Names two concrete use cases (knowing which messages are your own via sender == number, and addressing send_note_to_self) and an exclusion with the alternative to pick instead (list_accounts). This is the explicit when/when-not/alternative pattern.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description goes well beyond them: it discloses that the lookup carries no profile data, that name/given_name/family_name/about always return null, and that uuid is null when the number is unregistered. That is exactly the non-obvious behavior an agent needs to avoid misinterpreting the response.

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, each earning its place: purpose and return shape first, then a single routing sentence covering four alternatives. Zero filler and the most decision-relevant fact (null profile fields) is front-loaded.

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

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

No output schema exists, so the description carries the return contract itself — contact object with number/uuid, null uuid for unregistered numbers, and null profile fields — plus a full routing map to alternatives. Nothing an agent needs to call this 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% and the single parameter is already documented as E.164 in the schema; the description merely restates '(required, E.164)'. With the schema doing the work and only one param, baseline 3 is appropriate — no additional format or edge-case semantics are added.

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

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

States a specific verb (check) and resource (one phone number against Signal's servers) and immediately clarifies the scope: a lookup, not a profile fetch. It explicitly distinguishes itself from find_contact/list_contacts/get_avatar/get_user_status, so an agent can pick correctly 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?

Names four concrete alternatives with the exact condition that selects each: find_contact or list_contacts with all_recipients=true for profile name/about, get_avatar for photos, get_user_status for bulk checks, update_profile for editing your own profile. Explicit when-to-use and when-not-to-use routing.

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, so the 'Read-only' sentence is partly redundant, but the description earns its keep by disclosing the return payload ({base64}) and that the image format follows the sticker's contentType, usually image/webp. It does not discuss size limits or failure modes for missing sticker IDs.

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 the core action and result, then provenance, then the alternative tool. The '(required, hex string)' restatement and 'Read-only' repeat what the schema and annotations already carry, a small amount of 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?

No output schema exists, yet the description compensates by naming the exact return shape and format, plus the ID sources. For a two-parameter read tool, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real provenance detail beyond the schema: pack_id is a hex string from list_sticker_packs' packId field, and sticker_id maps to stickers[].id. That helps an agent construct valid calls rather than guess.

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 ('Fetch one sticker image from an installed pack') and even names the return encoding (base64). This clearly separates it from the sibling send_sticker / send_group_sticker tools that deliver rather than fetch.

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: 'Use send_sticker or send_group_sticker to send it instead of downloading it,' which is exactly the when-not guidance needed given the adjacent send tools. It also states where both IDs must come from (list_sticker_packs or add_sticker_pack).

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 indicate the operation is not read-only, not destructive, not idempotent, and open-world. The description goes further by disclosing the local-store read-marking side effect, the absence of a read receipt, the background service behavior, and the at-most-once-per-30s polling fallback. This gives an agent unusually rich operational 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 dense but front-loaded, opening with the tool's primary purpose before detailing side effects, alternatives, parameter behavior, and pagination. Every sentence carries operational value, especially given the absence of an output schema.

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

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

With no output schema, the description fully compensates by describing the return object shape, key fields, ordering, and has_more pagination. It also covers side effects, alternative tools, and the optional limit's behavior, leaving no critical invocation gap.

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

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

The single limit parameter is well covered by the schema, but the description adds important semantics missing there: the value is clamped to 1-500 and the newest messages are kept when more exist. That directly affects how an agent should invoke the tool and interpret results.

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: returns new unread incoming messages across all conversations. It immediately distinguishes this tool as the default way to check for new messages, helping an agent separate it from sibling tools such as get_conversation and list_conversations.

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 when to use this tool (default check for new messages) and names alternatives for related tasks: get_conversation for full chat history and list_conversations for an inbox overview. It also documents the side effect and points to send_read_receipt and mark_as_unread for receipt/undo behavior.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (one entry per input with recipient, number/username, uuid null when unregistered, isRegistered) and the discoverability caveat — both absent from annotations. It stops short of describing pagination or rate limiting, hence not 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?

Three dense sentences with zero filler: purpose and batching first, parameter formats and the at-least-one constraint second, return shape and usage caveat third. Every sentence carries distinct information and the purpose is front-loaded.

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

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

There is no output schema, so the description carries the burden of explaining return values and does so (uuid null when unregistered, isRegistered). Combined with the required-parameter constraint, the alternatives for contact lookup, and the discoverability caveat, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not encode: it restates the formats (E.164 for recipients, usernames or username links) and states the cross-parameter constraint 'at least one of the two is required', which the schema cannot express since required is empty.

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 ('Check whether phone numbers and/or usernames are registered on Signal') plus the scope ('in one batch query to Signal's servers'), and explicitly routes away from find_contact/get_profile for other needs. An agent can distinguish it from list_contacts or get_profile 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 an explicit trigger ('Use it before messaging an unknown number') and names the alternatives for adjacent needs ('For a contact's name or details use find_contact or get_profile'). It also warns about a false-negative case (numbers that hide discoverability), which is exactly the kind of when-not guidance an agent needs.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the SIGNAL_MCP_WEBHOOK environment variable takes precedence over the stored URL, which directly affects how the returned value should be interpreted. It does not cover error or failure behavior, so it falls short of fully rich disclosure.

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

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

Three short sentences with zero filler, and the return shape is front-loaded before the precedence rule and the sibling pointer. Every sentence carries distinct 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?

With no output schema, the description supplies the return format ({url} or {url: null}), the precedence rule governing the value, and the routing to the mutating alternative. Nothing an agent needs to call and interpret this 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, which is the baseline-4 case. The description confirms this explicitly ('No parameters.'), matching the empty schema with no ambiguity.

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 ('Return the webhook URL in effect') and even specifies the exact return shape ({url} or {url: null}). It names its counterpart sibling, set_webhook, so an agent can distinguish read from write 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?

Explicitly names the alternative ('Use set_webhook to change or clear it') and the condition that selects it, plus notes there are no parameters. An agent knows exactly when to call this versus the mutating sibling.

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 past the annotations (idempotentHint=true, destructiveHint=false, openWorldHint=false). It discloses what is read (encrypted local DB, key via macOS Keychain or Linux secret-tool, possible access prompt), what is written (local store only, nothing sent to Signal), idempotency semantics ('already stored messages are skipped, re-running is safe but slow'), and a concurrency constraint ('only one import can run at a time').

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 benefit, then prerequisites, then safety/idempotency/return shape. Every sentence carries operational information, but the description is dense and runs long for a zero-param tool; a minor trim would tighten it.

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

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

With no output schema, the description supplies the return shape ({imported, skipped, total, max_ts_ms, platform, source}). Combined with prerequisites, safety guarantees, idempotency, and the sync_desktop alternative, an agent has everything needed to call and interpret this 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?

Zero parameters, so the baseline is 4. The description correctly states 'No parameters' and adds no misleading param info, though there is nothing further to clarify beyond confirming the tool takes no input.

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+scope: 'Import the full message history from Signal Desktop on this machine into signal-mcp's local store.' It also names the concrete benefit (older messages visible to get_conversation, search_messages, export_messages) and explicitly contrasts with the sibling sync_desktop, so an agent can pick the right tool without opening a 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 routing: 'Use sync_desktop for later updates; it only reads messages newer than the last sync.' Prerequisites are spelled out (Signal Desktop installed and opened at least once, sqlcipher installed, database key available), which tells the agent exactly when this call will and won't work.

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=true, destructiveHint=false) by disclosing the network side effect (contacts Signal's servers, notifies the group), the admin-approval path (requesting member, onlyRequested=true, or the 'Pending admin approval' failure), the invalid/reset-link failure text, and the return fields. This is exactly the behavioral context annotations cannot carry.

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 action and required parameter, then layers usage routing, side effects, failure modes, and return handling. Every sentence carries distinct information and no sentence is filler, despite the overall length.

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

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

With no output schema, the description compensates by naming the returned fields (status, groupId, timestamp, send results) and the actionable failure strings. Combined with the routing guidance and side-effect disclosure, nothing an agent needs to call this 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?

Only one parameter and schema coverage is 100%; the schema already documents uri as 'Group invite link starting with https://signal.group/#'. The description restates the same format with an example, adding little meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Join a Signal group from an invite link') and immediately distinguishes the case it serves from the alternative ('groups you are not in' vs list_groups). An agent can route between join_group, create_group, and list_groups without opening a 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 says when to use it ('groups you are not in') and names the alternative for the other case (list_groups). It also tells the agent where to go next after success, using the returned groupId as group_id for send_group_message.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds far more: a quit message is sent to all members, you are removed from the member list, the group survives for others, naming an admin is mandatory when you are the sole admin, and the irreversible re-entry constraint (re-added or invite link). This is rich context well beyond the structured 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?

Purpose and the sibling alternative are front-loaded in the first sentence, followed by parameters and the return value. Dense but every clause carries information; only marginal tightening 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?

No output schema exists, yet the description states the return value ('status and group_id'), covers all three parameters including defaults, and discloses the admin-promotion prerequisite and re-entry consequences. Complete for an agent to invoke 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 would be 3, but the description goes further by giving the 'delete' default (false) and the consequence of setting it, which the schema does not state, and reinforces the group_id provenance. It slightly exceeds what the schema already provides.

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 ('Leave a Signal group yourself') and precisely distinguishes the scope from its closest sibling by naming terminate_group as the tool for ending the group for everyone. An agent can select 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?

Explicitly names the alternative (terminate_group) and the condition that selects it, plus a hard prerequisite ('if you are the group's ONLY admin you must name one, otherwise signal-cli refuses'). When-to-use, when-not-to-use, and the failure mode are all 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?

The annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the description goes well beyond them by disclosing the exact return shape (JSON array of E.164 numbers only, no registration status), the fact that it queries the running signal-cli daemon, and the common case of a single account. That is substantive behavioral context an agent 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?

Three short sentences, front-loaded with what it returns, then constraints, then the sibling routing. Nothing redundant; every clause carries 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?

No output schema exists, so the description properly compensates by specifying the return type and its exact contents, plus the daemon dependency and typical cardinality. 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?

There are zero parameters and schema coverage is 100%, so the baseline of 4 applies; the description correctly makes no attempt to invent parameters and confirms the call takes no arguments.

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

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

States a specific verb (List) and resource (Signal accounts registered in signal-cli on this machine), and explicitly distinguishes itself from get_own_number, the closest sibling. An agent can tell exactly which of the 70+ siblings this is without opening a 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?

Names the alternative tool (get_own_number) and the condition that selects it: this tool enumerates all registered accounts, while get_own_number returns the single sending/receiving identity. That is explicit when-to-use/when-not routing.

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 openWorldHint=false, and the description reinforces this with 'Read-only and local; nothing is downloaded.' It goes further by disclosing the empty-folder behavior and where attachments originate, which annotations cannot express.

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 return shape, then routing. Dense with semicolon-separated facts, but every clause carries information an agent needs; slightly long but not padded.

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

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

With no output schema, the description supplies the return structure ({filename, path, size, modified}, sorted by filename, empty when the folder is missing), which is exactly what is needed. Nothing required 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 still explicitly states 'No parameters,' removing any doubt about whether a path or filter argument 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 (list attachment files) plus the exact scope (the local ~/Downloads/signal-attachments folder). It is clearly distinguishable from siblings get_attachment (details for one file) and send_attachment (uploading), which it references by name.

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?

Routes the agent explicitly: 'Pass a filename to get_attachment for its details,' and clarifies the relationship to receive_messages and the background service that populates the folder. It lacks an explicit when-not-to-use statement, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context: it operates on the local store with 'no network call', which sharpens the openWorld hint into an actionable fact. It does not discuss result size or ordering, which is a minor gap.

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 purpose and the sibling routing, then parameters, then return shape. Dense and mostly waste-free, though the return-field enumeration runs long as one comma-separated tail.

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 exists, and the description compensates by naming the returned fields (number, uuid, name, given_name, blocked, etc.). With 100% parameter coverage plus return shape plus sibling routing, 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 goes beyond the schema: the schema says search matches 'name or number' while the description enumerates number, name, given/family name, nickname and username. It also spells out the tri-state blocked semantics and gives a concrete example for all_recipients.

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 contacts in signal-cli's local contact store) and immediately distinguishes itself from the sibling find_contact, which does the narrower single-person lookup. An agent can select 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?

Explicit when-to-use ('browse or audit contacts') and names the alternative with the condition that selects it ('to look up one person's number by name, find_contact is the shorter call'). 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 cover the safety profile (readOnly, idempotent, non-destructive, non-openWorld), and the description adds substantial context beyond them: it reads only locally stored messages, makes no Signal server call, marks nothing as read, and names come from the cached signal-cli contacts/groups. This is exactly the extra behavioral disclosure that structured fields cannot convey.

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

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

Front-loaded with purpose and scope, then alternatives, then behavioral caveats, then the return shape. Despite being dense, every sentence carries actionable information with no filler.

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

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

No output schema exists, so the description compensates by enumerating the full return shape (id, type, name, last_message, last_message_at, message_count, unread_count) and even explains how to pass the id onward. Nothing an agent needs to call and consume this 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?

With zero parameters the baseline is 4; the description confirms 'Takes no parameters,' which is consistent with the empty schema. There is no further parameter meaning to add.

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

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

States a specific verb (List) and resource (every conversation, direct and group) with scope ('in the local store, most recent first — an inbox overview'). It clearly differentiates itself from sibling readers like get_conversation, get_unread, and search_messages.

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

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

Explicitly routes the agent to alternatives with conditions: 'Use get_conversation to read one, get_unread for only new messages, search_messages to find text.' Nothing is left to inference about when to pick this tool versus its neighbors.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond them: the query is a server round-trip (not a local cache read) and it spells out the returned fields, which matters because no output schema exists.

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 tight sentences: what it does, the shape of the result, then when to use it. The routing hint to update_device/remove_device is front-loaded at the end where it is most actionable, and no sentence is filler.

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

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

For a parameterless read tool with no output schema, the description supplies exactly what is missing: the origin of the data, the returned field names, and the semantics of the notable value (device id 1 is the primary phone). An agent can call this and interpret the response without further documentation.

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 per the rubric this is a baseline 4. The description explicitly confirms 'Takes no parameters,' which is consistent with the empty schema and removes any doubt 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?

States a specific verb and resource ('List all devices linked to your Signal account') and adds the provenance detail that results come from Signal's servers rather than a local store. That scoping distinguishes it clearly from siblings like add_device, update_device, and remove_device.

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 two use cases (audit device access, obtain a device id) and routes to the tools that consume that id: update_device for rename and remove_device for unlink. Nothing is left to inference about when to reach for this 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 cover readOnly, idempotent and no-network semantics, but the description reinforces the no-network behavior and, importantly, enumerates the full return shape since no output schema exists. It doesn't mention pagination or large-store performance, which keeps it short of a 5.

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

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

Front-loaded with purpose and usage before the return-field enumeration, and every clause is dense and useful. The long field list is justified by the absence of an output schema, though it is still fairly heavy.

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 list tool with no output schema, the description fully documents the return fields (including pending/requesting/banned members and permission enums) and the local-store behavior. An agent has everything needed to call and interpret 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 coverage is 100%, so the schema already documents group_id. The description restates that group_id returns only that group but adds no syntax or format detail beyond the schema; 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?

States a specific verb and resource ('List the Signal groups this account knows') plus scope ('from signal-cli's local store'). Clearly distinguishes itself from mutation siblings like update_group and leave_group.

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 call it first to obtain the group_id that send_group_message, update_group, leave_group, terminate_group and set_expiration_timer require, and to check admin status. This names both the purpose and the downstream dependents, 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?

Annotations already cover the read-only/idempotent safety profile, so the bar is lower, yet the description adds substantial context: trustLevel states TRUSTED_VERIFIED, TRUSTED_UNVERIFIED and UNTRUSTED, and notes that UNTRUSTED blocks sending until re-trusted, plus that the tool never mutates trust. That is meaningful behavioral disclosure beyond the 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-loads the purpose, then the filter, then the return shape, then the trust semantics and usage trigger. Sentences are dense but every one carries information an agent needs, with no filler.

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

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

With no output schema, the description compensates by enumerating all returned fields (number, uuid, fingerprint, safetyNumber, scannableSafetyNumber, trustLevel, addedTimestamp) and explaining the enum-like trust levels. Nothing needed to call or interpret it 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 parameter is fully documented there, so baseline 3 applies. The description restates E.164 format and the omit-for-all behavior without adding 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?

States a specific verb and resource ('List stored Signal identity keys (safety numbers) and their trust levels, from the local store'), immediately distinguishing it from siblings like trust_identity and list_contacts. An agent knows exactly what data comes back without opening a 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 triggers ('Use it when Signal reports safety number changed or before trust_identity') and an explicit exclusion of what it does not do ('it does not change trust itself'), which routes the agent to trust_identity for mutations. The 'omit it for all' filtering condition is also 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 cover the safety profile (readOnly, idempotent, destructive=false, openWorld=false), so the bar is lower. The description still adds value beyond them: 'local only' scope, the full return array shape with the status enum values, and the presence of an `error` field.

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 dense sentences, front-loaded with the verb and resource, then filter semantics, then return shape, then cross-tool routing. No filler and nothing redundant with the schema.

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 exists, yet the description supplies the return record fields and status values, plus the single parameter's semantics and relationships to the two sibling scheduling tools. An agent has everything needed to call and interpret 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 coverage is 100%, so baseline is 3, but the description earns above baseline by spelling out what 'done' actually means — sent, cancelled, or failed — and restating the default. That clarifies the filter semantics more than the terse schema field does.

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+resource: 'List messages scheduled with schedule_message, ordered by send time.' It names the producing tool and the ordering, and clearly distinguishes itself from siblings schedule_message, cancel_scheduled_message, and run_scheduled_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?

Explicitly scopes default behavior (pending only) vs. include_done, and routes the agent by naming the id's downstream use (cancel_scheduled_message) and the complementary sender (run_scheduled_messages). No 'when-not-to-use' clause, but the effective context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description reinforces "Read-only" (mildly redundant) but adds genuine value by spelling out the returned pack structure, which no annotation conveys. It doesn't mention pagination or error behavior, but for a parameterless local list that gap is minor.

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 compactly covers the empty signature, the return shape, the safety profile, and the downstream siblings. Every sentence carries distinct information 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?

With no output schema and no parameters, the description compensates by documenting the exact array shape returned, including pack fields and nested sticker fields. An agent has everything needed to call it and consume the result.

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 per the rubric the baseline is 4. The description explicitly confirms "No parameters," leaving nothing ambiguous.

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 with scope ("List the sticker packs installed on this Signal account"). It is immediately distinguishable from siblings like add_sticker_pack, get_sticker, and upload_sticker_pack 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?

It routes the agent to the relevant siblings: use packId/sticker id with send_sticker, send_group_sticker or get_sticker, and use add_sticker_pack to install. It gives clear context for the tool's role in the sticker workflow, though it never states an explicit condition for choosing this listing tool over any other alternative.

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=false, destructive=false, idempotent=true, openWorld=false, but the description adds what those flags cannot: that the change is local-only, that already-sent read receipts and other devices are unaffected, that unknown ids are silently ignored, and the exact return shape {status, count}. The 'unknown ids are ignored' behavior is especially valuable side-effect disclosure.

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 action and the store scope, then layers consequence, scope caveat, parameter semantics and return shape in short clauses. Every sentence carries distinct information; nothing repeats the schema or annotations without adding 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?

There is no output schema, yet the description supplies the return contract ({status, count} where count is the number of ids passed), the idempotency guarantee, and the blast radius of the mutation. For a single-parameter local mutation tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description earns an extra point by telling the agent where valid ids come from ('exactly as returned by get_conversation, get_unread or search_messages') and what happens to ids that don't resolve. It doesn't add ordering or size-limit constraints, so it isn't a full 5.

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?

Names a specific verb (mark as unread) plus resource (messages) and scopes it precisely to the local signal-mcp store, then states the observable consequence ('so get_unread returns them on its next call'). It also distinguishes itself from the sibling it most resembles, send_read_receipt, calling it 'the opposite, outward action'.

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 motivating scenario ('e.g. to flag for follow-up') and points at the contrasting sibling (send_read_receipt) for the outward case. It stops short of explicit when-not conditions or edge-case routing, but the context is clear enough to choose between the two.

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 openWorldHint, idempotentHint, and non-destructive, so the bar is lower. The description still adds real context beyond them: the pin is publicly visible to all participants, the call contacts Signal's servers, and re-pinning is a no-op (restating idempotency in plain terms). Only the return shape and any auth/rate-limit caveats are left implicit.

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 visibility caveat before the routing advice and parameter notes; every sentence carries information. It is dense as a single block, and the parameter guidance is interleaved with usage guidance rather than separated, which slightly hurts scannability.

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 4-parameter mutation with no output schema, the description covers the missing return contract ('Returns {status: \'message pinned\'}'), the visibility consequence, the idempotent behavior, and both conversation-targeting modes. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds format meaning the schema lacks: E.164 for target_author, millisecond timestamp, and the provenance of the value ('message id in get_conversation'). It also restates the recipient/group_id mutual-exclusivity in prose. It does not, however, clarify failure modes for ambiguous or mismatched identifiers.

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 (pin) and resource (message) with explicit scope: at the top of a DM or group conversation, visible to all participants. It actively distinguishes itself from two siblings by name (send_note_to_self for private bookmarks, unpin_message for removal), so an agent can route correctly 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?

Explicit when-not guidance ('don't use it as a private bookmark — send_note_to_self instead') plus the inverse operation (unpin_message) and the recipient-vs-group_id selection rule including the 'neither is an error' edge case. Nothing about tool selection 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 destructiveHint=true, idempotentHint=true and openWorldHint=false, but the description adds material context beyond them: the operation is local-only, nothing is removed from Signal itself, it is irreversible locally, and it cascades into attachment records and search index entries. It also discloses the return shape {deleted, older_than_days}, which the absence of an output schema makes valuable.

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 text is a single dense paragraph that front-loads the core action before moving to parameter semantics, return value, and sibling routing. It is slightly long and the parameter sentence partially restates the schema default, but no sentence is wasted.

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

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

For a one-parameter destructive tool with no output schema, the description covers the action, its cascade effects, irreversibility, local-only scope, parameter semantics, return shape, and alternatives. An agent has everything needed to call it correctly or choose a sibling instead.

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 the positivity constraint ("must be positive") and the precise comparison semantics (timestamp older than now minus N days) that the schema's one-line description does not spell out. That is a modest but real increment over the structured field.

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 precise verb (delete) plus resource (locally stored messages older than N days) and explicitly scopes it to signal-mcp's database, including the cascading deletion of attachment records and search index entries. It also names the siblings it is not (delete_local_messages, clear_local_store), so an 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?

It gives an explicit when-to-use ("keep the store small") and routes the agent to two named alternatives with their distinguishing conditions: delete_local_messages for one conversation, clear_local_store to wipe everything. 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, openWorldHint=true), and the description still adds substantive behavior: the one-reaction-per-message rule, replace-vs-no-op semantics for repeated emoji, remove=true retraction with emoji still required, and that the change hits Signal's servers rather than local storage. It even names the return payload, which no output schema provides.

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 action and its purpose in the first clause, then layers targeting, semantics, and return value in a tight sequence. It is dense and semicolon-heavy, but every sentence carries distinct information rather than repetition.

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 six-parameter mutation with no output schema, the description covers sourcing the target identifiers, the mutual-exclusivity of recipient/group_id, replacement and retraction semantics, and the return shape. Nothing an agent needs to call this 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%, so the baseline is 3, but the description goes further: it specifies target_author as the sender's E.164, explains that target_timestamp is a millisecond value obtainable from get_conversation or a send_* result, and clarifies the recipient/group_id pairing and the default of remove. Only minor gaps remain (no note on timestamp unit edge cases).

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 precise verb+resource ('Add or remove your emoji reaction on a message') and scopes it to DMs or groups. It explicitly contrasts itself with the sibling text-reply tools (send_message / send_group_message), so an agent can route correctly without opening a 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 an explicit when-to-use ('to acknowledge without replying') and names the alternatives for the other case. It also states the routing rule between the two targeting modes ('Give recipient for a DM or group_id for a group; neither is an error'), 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?

Adds substantial behavior beyond the annotations: it stops the daemon and holds a lock file, the daemon restarts on the next call, received messages are saved locally, remote deletes are applied, nothing is marked read, and it errors on non-zero exit. These are exactly the side effects an agent needs to know before invoking a non-read-only tool.

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 fallback framing and the daemon/lock caveat before parameters, and each clause carries information. Slightly dense, but no sentence is wasted.

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

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

With no output schema, the description covers the return shape ('same shape as receive_messages'), error behavior, and local-store side effects. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all six parameters with defaults. The description restates timeout, max_messages and the ignore_* flags, adding only marginal framing ('skip downloading those'), 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+resource ('receive messages by running signal-cli receive directly, bypassing the daemon') and immediately frames it as a troubleshooting fallback, which distinguishes it from the receive_messages / get_unread 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?

Explicitly names when to use it ('only when receive_messages / get_unread fail because the daemon is stuck') and the alternatives it replaces, plus the condition that resolves the choice. 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 provide only generic hints (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds substantial non-obvious behavior: edits and remote deletes are applied to stored messages rather than returned, receipts are returned but not stored, nothing is marked read, and a fallback shape {note, messages} is returned if the receive lock is held. This is exactly the kind of context annotations cannot convey.

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

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

Dense and front-loaded: behavior, routing, parameters, side effects, and return shape in a compact block. Every sentence carries signal, though the return-field enumeration is a long list that slightly taxes readability.

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 non-idempotent, open-world polling tool with no output schema, the description covers side effects (what is stored vs returned, edits/deletes applied, nothing marked read), the return shape, and the lock-contention fallback. 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 description coverage is 100%, so the schema already documents timeout and max_messages. The description restates the defaults but adds no syntax or constraint details beyond the schema. Baseline 3 for full schema coverage.

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

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

States a specific verb and resource ('Poll the signal-cli daemon once for newly arrived messages and save them to the local store') and explicitly differentiates from siblings get_unread and receive_direct, with a clear default preferred path.

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

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

Explicitly states when to use this vs alternatives: 'Normally use get_unread instead', and 'use receive_direct only if the daemon is stuck'. This is textbook when/when-not/alternatives 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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further: it discloses that changes sync to linked devices, that forget is irreversible and wipes identity keys and sessions, that hide/forget are mutually exclusive with an error on conflict, and that the result status is 'removed'. That is substantial behavior beyond the 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?

Dense but front-loaded: the core action and its scope boundaries come first, then parameter caveats and the result shape. Every sentence adds an actionable fact (alternatives, irreversibility, exclusivity, return value) without 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?

Despite having no output schema, the description states what is returned ('status removed' and number), covers the destructiveness and irreversibility of forget, and routes to sibling tools. 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 baseline is 3, but the description adds real meaning: it clarifies that hide keeps data versus forget deleting ALL data, and it documents the mutual-exclusivity constraint and error behavior that the schema does not express. It stops short of five only because the core per-parameter semantics largely duplicate the schema.

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

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

States a specific verb (Delete) and resource (a contact's entry) and immediately delimits scope by saying it does not block, delete messages, or stop messaging. This clearly distinguishes it from siblings block_contact and update_contact without opening their 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?

Explicitly names when-not to use it ('use block_contact for that') and names the alternative for a related operation ('To rename instead, use update_contact'). Both exclusion and redirect are stated rather than implied.

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so the safety profile is covered; the description goes further by disclosing the operational consequence (device immediately stops sending and receiving), the irreversibility of the unlink, and the exact failure mode ('This command doesn't work on linked devices') when signal-mcp was set up via signal-cli link.

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?

Dense but front-loaded — the destructive action and its consequence come first, then constraints, then return values, then the sibling alternative. Nearly every clause carries information, though the sentence count could be trimmed slightly.

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

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

With no output schema, the description still states the return payload ('status' of 'device removed' plus device_id), covers the precondition, the failure case, and the alternative tool. Nothing needed 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% so the baseline is 3, but the description adds real constraint meaning beyond the schema: device_id must reference a linked device and must not be 1 (the primary). That is a validation rule an agent cannot infer from the schema 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?

States a specific verb and resource ('Permanently unlink a device from your Signal account') and immediately distinguishes itself from the three sibling device tools (list_devices, add_device, update_device). 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?

Gives explicit when-to-use (permanent unlink), the alternative for the adjacent intent ('To only rename a device, use update_device'), and the recovery path (relink via add_device). It also names a hard precondition for calling it at all: signal-mcp must be the primary device.

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 mark this as destructive, idempotent, not read-only, and open-world. The description adds valuable context beyond those hints: the exact failure on linked devices, the immediate account impact, and how to undo the operation by calling set_pin.

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, short, and every sentence carries useful information: purpose, effect, device constraint, undo path, return value, and alternative tool. No sentence is wasted.

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

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

For a zero-parameter destructive tool, the description is complete: it covers the side effect, device limitation, undo path, return value, and the relevant alternative. Annotations cover the safety profile, and no output schema exists, so the stated return value is a useful addition.

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

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

The tool takes zero parameters, so the baseline is 4. The description simply restates that there are no parameters, which matches the empty schema and adds no further 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 states a specific verb and resource: removing the Registration Lock PIN from a Signal account. It also immediately distinguishes the effect from set_pin by noting that set_pin should be used to change the PIN instead of removing it.

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

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

It gives explicit operational context: primary device only, linked-device failure mode, immediate real-account effect, and the alternative set_pin for changing rather than removing the PIN. This leaves little 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 only declare readOnly=false, idempotent=false, destructive=false, openWorld=true. The description adds substantial context beyond that: due messages are sent late rather than dropped, each job is delivered once, failed jobs are not retried, it is safe to call when nothing is due, and the exact return shape. It is consistent with idempotentHint=false.

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 core action in the first sentence, then layers delivery semantics, safety, return shape, and sibling routing. Every sentence carries distinct information; the dense return-value sentence is justified because there is no output schema.

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 parameters and no output schema, the description fully compensates by documenting retry behavior, the sent/failed status values, the returned fields, and safe no-op behavior. 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?

The tool takes no parameters, and the description confirms 'No parameters,' so there is nothing to disambiguate. Per the rubric, zero params yields a baseline of 4.

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 every scheduled message whose send_at time has passed and is still pending') and explicitly contrasts with the sibling tools schedule_message and list_scheduled_messages. An agent can distinguish this from the other scheduled-message tools without opening a 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-invoke guidance ('call this ... after their time'), names the cron alternative, states the prerequisite condition (send_at passed and pending), and routes to schedule_message / list_scheduled_messages for the other lifecycle stages. Exclusions are covered via the 'still pending' condition.

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 only record the write/non-idempotent/non-destructive profile; the description adds the critical behavior that nothing is actually sent at the scheduled time unless run_scheduled_messages (or the CLI) runs. It also discloses persistence to the local store and the exact return payload, which annotations cannot convey.

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

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

The purpose and target rule are front-loaded, and the behavioral caveat and alternatives are grouped sensibly at the end. It is longer than strictly necessary ('message (required): the text' partly echoes the schema), but almost every sentence carries distinct, load-bearing 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?

With no output schema, the description compensates by stating the return shape {job_id, send_at, status}, the send-time dependency, and the target constraint. An agent has everything needed to schedule, review, and understand the deferred-send model.

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 genuine constraints beyond the schema: send_at is local time with no timezone, accepts two concrete formats, and 'must be in the future'. It also restates the mutually exclusive target rule with the E.164 requirement.

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

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

The description opens with a specific verb+resource+mechanism: 'Save a text message in the local store to be sent at a future time.' It explicitly distinguishes itself from immediate-send siblings by naming send_message and send_group_message as the 'send now' alternatives, so an agent can route correctly 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?

It names the full lifecycle siblings and the condition that selects each: list_scheduled_messages to review, cancel_scheduled_message to cancel, send_message/send_group_message for immediate sending. It also states the target-selection rule ('exactly one target: recipient or group_id'), removing ambiguity.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), but the description adds substantial behavioral context beyond them: no Signal server call, nothing marked read, only locally stored messages are found, FTS failure falls back to substring matching, and invalid dates return an error. These are non-obvious traits an agent 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 purpose then capabilities then per-parameter notes in one dense paragraph; every clause carries information. It does duplicate some schema details (date examples, limit clamp), which keeps it just short of ideal.

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 exists, yet the description enumerates the returned fields (id, sender, sender_name, recipient, group_id, group_name, body, timestamp, attachments) and ordering (newest first), plus pagination and error behavior. An agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: multiple words must all occur (AND semantics not in the schema's 'keyword or phrase'), empty query returns [], and boundary examples for since/until. It repeats the limit clamping and date exclusivity already in the schema.

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

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

States a specific verb (full-text search) and resource (message bodies) with a precise scope: 'across all conversations in the local store'. It explicitly distinguishes itself from get_conversation for reading a chat in order, so an agent can route 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?

Names the alternative ('Use get_conversation to read a chat in order') and defines the boundary conditions: local device only, no server call, nothing marked read. The when-to-use and when-not-to-use conditions are both 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?

Annotations already declare a non-read-only, open-world, non-idempotent write, but the description adds substantial context beyond them: a 20-per-minute send rate limit where calls wait rather than fail, duplicate sends on repeat, errors for files outside allowed roots or hidden files, local-store persistence, and the return shape {status, timestamp}.

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 alternatives, and its length is largely justified by 15 parameters. However, it is a dense single paragraph with semicolon-separated clauses, so structure could be improved for scanability.

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 high parameter count, absent output schema, and rich annotations, the description is complete enough: it covers purpose, alternatives, addressing, file constraints, behavioral caveats, rate limits, persistence, and return values. No critical calling information 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 real meaning beyond the schema: path and paths are mutually exclusive with one required, recipient and username are mutually exclusive, files must lie in allowed send folders, and quote fields only shape the quote bubble. The schema still carries most per-parameter detail, so this is not a full 5.

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: 'Send one or more files ... to one Signal contact in a single message.' It explicitly distinguishes this tool from send_group_attachment, send_message, and send_sticker, so an agent can route correctly without opening sibling 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?

It names the alternatives and the conditions that select them: use send_group_attachment for groups, send_message for text only, send_sticker for stickers. It also states addressing rules (recipient or username, exactly one) and file-source restrictions, leaving little 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 declare readOnlyHint=false but destructiveHint=false, which is ambiguous on its own; the description resolves this by clarifying it 'changes nothing locally' and 'contacts no one else,' and adds the one-way direction and the literal return value. That is real context beyond the structured hints.

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 the tool does, then trigger, then side-effect profile, then return value, then alternative. Every sentence carries distinct information with no filler.

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

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

There is no output schema, but the description states the exact return status ('contacts synced to linked devices'), covers side effects, directionality, and the alternative tool. Nothing needed 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?

Zero parameters, so the baseline is 4. The description reinforces this with 'Takes no parameters,' which is helpful but adds nothing the empty schema does not already imply.

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 contact list as a sync message) plus the direction of flow, 'one-way from this device outward.' It explicitly contrasts with the sibling send_sync_request, so an agent can distinguish it without opening 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 concrete trigger condition ('when contacts added or renamed through signal-mcp do not appear on your phone or desktop') and names the alternative ('to pull data from the primary device instead, use send_sync_request'). This is explicit when-to-use plus alternative routing.

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 the safety profile (readOnly=false, idempotent=false, openWorld=true), so the bar is lower, yet the description adds substantial context: sendable-folder restriction with default roots and env override, error on hidden files, contact with Signal servers, non-idempotency (duplicate sends), a 20/min shared rate limit that waits rather than fails, and store persistence.

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 sibling routing, then groups related concerns (files, caption/media flags, quoting, notification, side effects). It is dense and long, but with 14 parameters each clause carries information, so little is wasted.

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

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

For a 14-parameter, non-idempotent mutation tool with no output schema, the description covers everything an agent needs: file constraints, flag semantics, quorum/quote behavior, side effects (server contact, rate limit, local store), and the return shape {status, timestamp}.

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 baseline is 3. The description goes beyond the schema by stating that path/paths are mutually exclusive with one required, and that quote_attachments/quote_text_styles/quotes only shape the quote bubble, but most parameter meaning is already documented in the schema.

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