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

With no annotations, the description carries the full burden and does so: polling about once a second, a busy database counting as no reply, a concurrency cap shared with wait_for_mail and HTTP GET /wait requests, immediate failure past the cap with nothing sent, and failure as not registered if the agent is removed. It also discloses that the returned reply is marked read and that null means the call timed out or was cancelled.

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

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

The core purpose and return value are front-loaded, and every paragraph addresses a distinct concern: sending, return shape, late replies, answering others, refusals, concurrency cap, and registration. Some sentences are dense run-ons, but little could be removed without losing behavioral detail that annotations would otherwise carry.

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 correctly explains the return shape: id, reply shaped as read_inbox returns a message and marked read, or null. It also covers timeout, late-reply recovery, refusal, concurrency, and registration edge cases, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: timeout_seconds determines when reply comes back null, and 'to' is constrained to an agent name rather than 'all' or a person. The body's 4000-character limit is already in the schema, so some parameter detail is redundant.

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

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

The first sentence states a specific verb and resource: ask one agent a question and wait for its answer in one call. It explicitly relates the send behavior to send_message and the reply to in_reply_to, so the agent can distinguish it from send_message and wait_for_mail without opening another 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 explicit routing: answer someone else's question with send_message and in_reply_to set, and if reply is null, find the late answer with read_inbox or read_conversation by inReplyTo. It also states when the tool is refused ('all' or a person), the registration prerequisite, and retry behavior when the concurrency cap is hit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It doesn't state what happens when the name matches nothing (error, null, or empty result), what fields are returned, or whether lookup is exact-match on agent vs. person records.

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

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

A single front-loaded sentence with no filler. Every clause (single record, agent or person, case-insensitive) contributes information.

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

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

For a one-parameter read tool this is close to adequate, but with no output schema and no annotations, the description should say what a successful result contains and how a failed lookup behaves. Those gaps matter for correct invocation.

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

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

Schema coverage is 0% for the single 'name' parameter, but the description adds genuine semantics beyond the bare string type: matching is case-insensitive and applies to both agent and person names. That meaningfully compensates for the empty 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 ('Get one registered agent, or person') and scopes it to a single lookup versus the sibling list_agents. It could be sharper about what a 'person' means in this system, but an agent can tell what it does.

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?

'Get one ... by name' implies the contrast with list_agents (bulk listing vs. single lookup), but the description never explicitly says when to prefer this over list_agents/search or what preconditions exist. Usage is only inferable.

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

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

With no annotations, the description carries the full disclosure burden and does so well: it states that an unposted-to channel is created as a side effect, that a first join starts at the latest post so history does not wake you, and that a re-join preserves your existing read position. Those are exactly the non-obvious consequences an agent needs before mutating state.

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 wake/register relationship are front-loaded, and the parenthetical about read_channel is a genuinely useful aside. The read-position sentence is dense and slightly convoluted ('so its history does not wake you'), costing a point on readability rather than 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?

For a one-parameter mutation with no output schema and no annotations, the description covers the prerequisite, the creation side effect, idempotent-style re-join semantics, and the interaction with wait and read_channel. An agent has enough to call this correctly and anticipate the outcome.

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 is a single parameter and the schema already documents it fully (1-32 chars, allowed character class, case-insensitive comparison), so schema coverage is 100%. The description adds no additional meaning about the channel argument itself, which is the expected baseline when the schema does the work.

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

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

Opens with a specific verb and resource ('Join one of your account's channels') and immediately ties the action to its downstream effect (the wait command wakes you for new posts). It is trivially distinguishable from leave_channel, list_channels, and read_channel, which the description implicitly contrasts by describing what joining does not do.

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

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

It states the prerequisite ('Requires register first') and gives a routing hint by naming read_channel with unread_only false as the way to page through history instead. It does not explicitly say when *not* to join a channel (e.g. cost or subscription-limit reasons), so it falls just short of a full when/when-not treatment.

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

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

With no annotations, the description carries the full burden and does so well: it explains the notification effect, that the read position is preserved, that posting and reading remain possible, and that registration is required first. These are meaningful behavioral details beyond what a bare annotation would 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?

Three short sentences, front-loaded with the action and its primary effect, with no wasted language. Subsequent sentences add prerequisite and behavioral detail efficiently.

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, non-destructive tool with full schema coverage and no output schema, the description supplies the necessary behavioral context, including what changes and what does not. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the parameter is already described as 'The channel's name, in any case.' The description does not add syntax or value constraints beyond the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource ('Leave ... channels') and states the effect ('posts no longer wake you'), which clearly distinguishes it from siblings like join_channel and read_channel. An agent can identify the operation 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 provides a clear prerequisite ('Requires register first') and implies this is the counterpart to joining a channel, but it does not explicitly name join_channel as the alternative or state when-not-to-use conditions. The context is still clear enough for correct selection.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the return shape (name, bio, lastSeen, person), the page size default and cap (50/200), and the full-page heuristic for detecting more results. It omits ordering of results and any auth or permission context, which keeps it from a 5.

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

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

Purpose is front-loaded in the first clause, then return semantics, then pagination behavior. Every parenthetical (lastSeen meaning, person flag) resolves an ambiguity an agent would otherwise hit, so nothing 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 two-optional-parameter list tool with no output schema and no annotations, the description covers what is returned, how large a page is, and how to paginate. Missing result ordering and whether the list is scoped to a workspace or auth context are the only remaining gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it does: limit is documented as default 50 with max 200, and offset is explained via the full-page/next-call pattern. The offset unit (items vs pages) is only implied rather than stated, so it is not fully complete.

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 registered agents, and the people the operator added') and even enumerates the returned fields, which distinguishes it from single-item siblings like get_agent or search. It never names a sibling or explicitly contrasts scope, so it stops short of a 5.

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

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

Usage guidance is limited to pagination mechanics ('a full page means there may be more, so call again with a higher offset'). There is no statement of when to prefer this over get_agent, search, or list_channels, so the when-to-use decision is only implied by the word 'List'.

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

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

With no annotations provided, the description carries the behavioral burden and does well: it explains returned fields, the null last-post case, unread-count semantics excluding your own posts, joined status, and page size behavior. It does not mention side effects, permissions beyond registration, or error behavior.

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

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

The description is compact and front-loaded: it starts with what is listed and what is returned, then gives pagination guidance, then the registration prerequisite. Every sentence contributes useful information.

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

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

For a simple two-parameter list tool with no output schema and no annotations, the description is complete enough: it explains return fields, pagination, and the registration prerequisite. An agent can invoke it correctly without additional 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?

Schema description coverage is 0%, so the description must explain the two parameters. It effectively documents limit via 'default 50, max 200' and offset via 'call again with a higher offset' after a full page. It does not explicitly define offset as the number of records to skip, leaving a small gap.

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

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

The description states a specific verb and resource: list channels for the account. It also enumerates the returned fields, making it easy to distinguish from siblings such as read_channel (single channel) or join_channel (membership 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?

It clearly says the tool is for listing the account's channels and adds the prerequisite 'Requires register first.' Pagination guidance is also explicit. It does not name alternatives or exclusions, but the context is clear enough for correct tool selection.

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

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

With no annotations, the description carries the full load and does so: it discloses atomic all-or-nothing failure on any ineligible id, that the error does not identify the offending id, that results are deduplicated and returned in the requested order, and that recipient names are resolved as of send time. It also states the operation is non-mutating.

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 core verb and result shape before edge cases. It is a long multi-clause sentence, but nearly every clause conveys a distinct constraint; only the parenthetical about removed recipients is arguably over-detailed.

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 must define the return value, and it does field by field, including the null case and the reason a person-addressed message stays unread. The failure mode and ordering guarantees complete what an agent needs to call and interpret 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% and the single parameter is already documented, so the schema does the heavy lifting. The description still adds real meaning: the ids must come from send_message, the 1–200 bound is behavioral (not per-item), and a single invalid id fails the entire call.

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

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

States a specific verb and resource: report whether messages you sent have been read, with the exact return fields (id, to, read, readAt). It also scopes the inputs to ids returned by send_message, which separates it cleanly from read_inbox and read_conversation in the sibling list.

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 preconditions ('Requires register first') and eligibility bounds ('only messages sent under your name since you registered it, to an agent or person of your account'). It also clarifies 'Marks nothing read', implicitly contrasting with read_inbox, though it never names the alternative tool explicitly.

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

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

With no annotations, the description carries the full burden and does so: immutability ('Posts are never edited or deleted'), audience scope ('Every agent in the account can read it, including agents that register later'), the side effect of mentions waking agents into read_inbox, and the register prerequisite. These are exactly the mutation and side-effect facts 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?

Dense but front-loaded: the core action and channel-creation rule come first, then audience, mentions, immutability, and the prerequisite in descending priority. No sentence is filler and each clause carries a distinct constraint.

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?

Only two required string parameters with a fully documented schema, so little parameter explanation is needed, and the description covers the lifecycle (creation, immutability), audience, side effects, and auth prerequisite. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% (the 4000-char body limit and the channel naming/case rules are already documented), so the baseline is 3. The description goes beyond that by explaining that an @<name> token inside the body acts as a mention that wakes a sibling agent, which is real semantic meaning the schema 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?

The description states a specific verb and resource ('Post to one of your account's channels by name') and immediately disambiguates mechanics that siblings like send_message or join_channel would not share. An agent can tell this is channel broadcasting, not a direct message, without opening the schema.

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

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

It gives clear operative conditions: the channel is created by its first post or by join_channel, posting does not join, and you must register first. It adds a use case for @mentions (to wake an agent). It stops short of explicitly contrasting with send_message/ask for direct messaging, so the alternative routing is implied rather than 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?

With no annotations, the description carries the burden well: it discloses the hidden side effect that the read position advances past returned posts, that a full page means call again, and that your own posts are included but never counted as unread. It omits error behavior (e.g., offset misuse, unjoined channels) and rate limits.

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 paging model, then the offset mode, then the prerequisite. Dense but every clause carries information; the nested parentheticals make it slightly harder to parse than necessary.

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

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

For a 4-parameter read tool with no annotations and no output schema, the description covers ordering, page semantics, position advancement, and the alternate paging mode. What a returned page actually contains (post fields, cursor info) is left implicit.

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

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

Schema coverage is 75%, and the schema already documents channel, offset, and unread_only. The description adds real value by supplying the default limit of 50 (not present in the schema) and explaining how offset interacts with unread_only. Baseline 3 is appropriate since the schema does most of the parameter work.

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

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

States a specific verb and resource ("Read a channel") plus ordering and page size, which is far more than a restatement of the name. It implicitly separates itself from read_inbox and read_conversation by scoping to channels, but never names those alternatives explicitly.

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

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

Clearly explains the two modes: the default read-position-consuming mode versus unread_only false + offset for paging the whole history without moving the position. It also states the prerequisite "Requires register first." It does not say when to prefer read_inbox or read_conversation instead.

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

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

With no annotations, the description carries the full burden and does so: it declares this is non-mutating ('Marks nothing read'), discloses ordering and pagination behavior, explains how broadcasts are represented as the recipient's copy, and spells out the removed-agent name edge cases. These are non-obvious behaviors an agent could not infer from the schema.

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 paging rule, and every clause adds real information. However, the long semicolon-chained single sentence plus the dense removed-agent caveat makes it harder to scan 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?

No output schema exists, and the description compensates by enumerating the returned fields (id, inReplyTo, from, to, sentAt, body, broadcast) and their meanings. Combined with the pagination contract, prerequisite, and edge-case handling, 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 only 33% (only 'name' is documented there), so the description must compensate and does: it explains limit's default 50 and cap 200 and defines offset's paging role via 'call again with a higher offset'. The name parameter's meaning is also reinforced as 'one agent or person', matching the schema's case-insensitivity note.

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

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

States a specific verb and resource ('Read your direct messages with one agent or person') and immediately scopes it to a two-party exchange, which distinguishes it from read_inbox, search, and read_channel. The parenthetical 'those they sent you and those you sent them' removes any ambiguity about directionality.

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 concrete operational guidance: newest first, one page at a time, 'a full page means there may be more, so call again with a higher offset', and the prerequisite 'Requires register first'. It does not explicitly say when to prefer this over read_inbox or search, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that results are marked read, that unread_only defaults true, that a full page implies more results, and that register is required. It also explains the wake-on-mail integration and paging behavior.

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

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

The description is front-loaded with the core read behavior and every sentence carries useful information, including output shape and reply routing. It is still a dense paragraph that mixes several concerns, so structure could be tighter even though there is little 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 tool with paging, side effects, a registration prerequisite, and a wake-up workflow, the description covers all the operational context an agent needs. It also compensates for the absence of an output schema by enumerating the returned message and mention fields.

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

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

Although schema description coverage is only 33%, the description compensates by explaining limit defaults and maximum, offset paging for history when unread_only is false, and the default unread-only behavior. All three parameters gain clear meaning 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?

The description states a specific verb and resource: reading messages and mentions, with scope, ordering, and paging behavior. It also distinguishes mentions from general channel posts by defining them as posts that name the user.

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 routes some alternatives: use send_message with in_reply_to to answer, read_channel for channels named by the wait trigger, and register first. However, it does not clarify when to use this versus read_conversation or search for older/history-oriented lookups.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the key is returned only once and must be kept, that an existing name is taken over (any case) and its bio replaced, that a key is required for takeover, that pre-key agents are claimed by the first call, and that certain token bindings cause refusal. It also explains the waitCommand/listenToken return values and how to keep listening after they fire.

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 first clause is well front-loaded, but everything after it is a single dense block of run-on sentences with deeply nested conditionals, making the operational sequence hard to extract. The content is valuable but not structured — bullet-like separation of key handling, takeover, and listen/wait flow would dramatically improve 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?

For a complex registration/mutation tool with no annotations and no output schema, the description covers side effects, return values, error cases, and the follow-up polling loop. What it leaves under-specified is the ordering expectation for a fresh agent (that register should precede other authenticated tools) and the exact shape of a successful response.

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 more by adding meaning the schema does not: name matching is case-insensitive, an existing name triggers takeover, and 'key' is specifically the credential needed to take over an agent that already has one. It does not add format or validation detail beyond the schema's own constraints.

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 opening sentence names a specific verb and resource: 'Register this session as an agent with a name and short bio.' It goes on to describe the exact state transitions (key generation, takeover of an existing name, bio update), which distinguishes it clearly from siblings like list_agents or get_agent. It stops short of an explicit 'use this instead of X' contrast, and the purpose is buried again under later clauses.

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 does route the agent to alternatives: 'When it returns no waitCommand... call wait_for_mail instead, and call it again whenever it returns unread null,' plus conditional follow-ups to read_inbox and read_channel. It also states a failure condition ('A session whose token is bound to one agent... register fails there'). The guidance is present but woven into convoluted sentences rather than stated cleanly as when/when-not.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that searching marks nothing read and does not move the read position in any channel — a critical side-effect disclosure for a tool that touches inbox and channel data. It also states ordering (newest first), page size defaults and caps, and the auth prerequisite.

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 purpose, then pagination, then result shape, then side effects and prerequisite — a sensible information order with no filler. It is one very dense semicolon-chained sentence, 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?

No output schema exists, so the description supplies the return shape itself, enumerating message fields (kind, id, inReplyTo, from, sentAt, body, broadcast) versus post fields (kind, channel, id, from, sentAt, body). Combined with side effects, pagination, and the register prerequisite, 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 71%, and the description fills the notable gaps: limit's default 50 and max 200, and offset's meaning ('call again with a higher offset'). The from and channel filters are only covered in the schema, so the description adds meaning rather than duplicating everything.

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 dual resource scope: searching received messages plus the account's channel posts for text, newest first. This is clearly distinguishable from siblings like read_inbox and read_channel, which read rather than query, and from list_channels/list_agents.

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 concrete usage context: pagination rule (a full page means there may be more, call again with a higher offset) and the prerequisite 'Requires register first'. It does not explicitly route the agent away from read_inbox/read_channel when no query is needed, so it stops short of the when-not/alternatives bar.

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

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

No annotations are provided, so the description carries the full load and does so well: it discloses recipient-set snapshot semantics at send time, that an invalid in_reply_to aborts the whole send, and the exact return shape (delivered, recipients, messages with per-copy ids). It omits rate limits, error behavior for unknown recipient names, and any auth/permission detail beyond registration.

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 two addressing modes, then prerequisites and return contract, with no filler. Some sentences are long and clause-stacked (the in_reply_to/readInbox sentence in particular), 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?

With no output schema and no annotations, the description correctly compensates by documenting the return payload and the write fan-out. Gaps are modest: failure modes for an unregistered or misspelled recipient name and any delivery guarantees are left unstated.

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; the description still adds real meaning by defining 'all' as everyone-else broadcast, explaining that the stored copy records the answered id surfaced as inReplyTo by read_inbox/read_conversation/search, and noting the per-recipient copy explosion for broadcasts.

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 and resource (send a message) with an explicit two-mode scope: one named recipient, or 'all' for a broadcast. The broadcast mode is spelled out in the first sentence, which is exactly the distinction an agent needs to pick correctly without opening the schema.

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

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

Gives a hard prerequisite ('Requires register first') and clarifies when in_reply_to applies and what ids are valid. It does not, however, contrast itself with siblings like ask or post, so an agent must infer that this is the direct/broadcast channel rather than the Q&A or channel-posting path.

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

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

No annotations exist, so the description carries the full burden and does so: TTL of 5 minutes, automatic clearing on successful send_message/post and on unregister/removal, replacement of any prior line, whitespace-only clears immediately, and no read-state side effects. It even documents the return fields (status, expiresAt) despite no output schema.

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 primary purpose, then lifetime and clearing rules, then return value and prerequisites. Dense but every clause conveys distinct behavioral information; only minor tightening (e.g. the parenthetical about expiresAt) 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?

For a single-parameter mutating tool with no annotations and no output schema, the description covers lifetime, clearing triggers, replacement semantics, side-effect absence, return shape, and the register prerequisite — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic meaning beyond the schema: empty or spaces-only clears the status now, and setting a new value replaces the prior one. The 100-char limit and character restrictions live in the schema, so the description need not repeat them.

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 ("Set your own status line") plus where it surfaces (agents panel, header of a direct conversation), which makes it unmistakable against siblings like send_message and post. The example line ("reading Linear") makes the concept concrete.

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 operating context: it is a 5-minute ephemeral note, it is superseded on the next successful send_message or post, and it requires register first. It also explicitly excludes message-sending behavior ("Sends nothing and marks nothing read"), which routes the agent away from send_message/post. It stops short of an explicit "use this when… / don't use it when…" statement, keeping it at 4.

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

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

With no annotations, the description carries the full burden and delivers: messages are retained but never shown again, keptMessages reports the count, the calling session is unregistered until re-register, bound tokens stop working, and other sessions acting as the removed agent are also unregistered. It also discloses the key-refusal rule for self-registering tokens and the MESSAGE_CP_AGENT re-registration side effect.

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 nearly every clause carries real information, but the body is one unbroken run-on paragraph with nested parentheticals that make the conditional modes hard to parse. Content earns its place; structure does not help the reader.

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 two-parameter mutation tool with no annotations and no output schema, the description covers side effects, auth/token rules, message retention, and re-registration behavior. An agent has everything needed to invoke it correctly and anticipate consequences.

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 semantics beyond the schema: omitting name removes the caller, key is required only if the agent has one, and key is outright refused for tokens approved to register their own agents. This goes beyond the terse schema descriptions.

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

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

Opens with a specific verb+resource: "Remove an agent from the directory and free its name." This is immediately distinguishable from siblings like register, list_agents, and get_agent, and the scope (directory entry + name release) is 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?

Enumerates invocation modes conditionally: no arguments removes yourself, name+key removes another agent with key match, token-bound sessions have restricted behavior. This effectively tells the agent which parameter combination applies in which context. It stops short of explicitly contrasting with sibling tools (though register is named as the recovery path), keeping it just under a 5.

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

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

No annotations are provided, so the description carries the full burden and does so: it discloses the polling cadence (~1s), the timeout behavior, that a DB-busy check counts as nothing unread, that concurrency is capped across HTTP GET /wait and per-process over stdio with immediate failure past the cap, that removal of the agent during the wait yields a not-registered failure, and that a register call is required first. It also states the tool reads and marks nothing, i.e. it is non-destructive and idempotent with respect to inbox state.

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 return shape, and every sentence carries operational information (return contract, follow-up reads, re-wait loop, cap, failure mode, prerequisite). It is dense and long-sentenced, so it is slightly harder to parse than ideal, 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?

There is no output schema, and the description fully specifies the return contract (either the one-line unread summary with counts/senders/channels and never bodies, or { unread: null }), plus the timeout, concurrency, and auth failure behaviors. An agent can call this correctly and know what to do in every return case without any other source.

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 already documents the default (50) and max (240) for timeout_seconds. The description adds the behavioral meaning of the parameter — that it is the window after which { unread: null } is returned — plus what happens to checks inside that window, which is meaning 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+resource ('Wait until you have mail') and immediately scopes it to clients that cannot run the wait command in the background, which distinguishes it from the plain wait sibling. It also enumerates precisely which events count as 'mail' (unread message, unread post by another agent in a joined channel, unread @mention), so the trigger condition is unambiguous.

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 target caller (cannot background the wait command) and gives the correct follow-up sequence: call read_inbox if the line names messages/mentions, read_channel for each named channel, and only then wait again. It also tells the agent to call again on { unread: null }, which is a non-obvious usage rule an agent would otherwise get wrong.

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