RogerThat

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

With no annotations, the description carries the full burden. It discloses that recovery_token is shown only once and session_token is short-lived, used for Bearer auth. This is good behavioral context, though it omits potential side effects or prerequisites.

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

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

Three sentences, front-loaded with purpose, followed by return values and critical usage notes. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description explicitly lists all return fields and their significance. For a no-parameter tool, it provides complete context for usage and 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?

The input schema has no parameters, so schema description coverage is 100%. The description adds no parameter details, which is acceptable as there are none to document. The baseline of 4 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 clearly states the tool creates a RogerThat account and lists the return values, including a note about recovery_token being shown only once. This distinguishes it from sibling tools like create_channel and create_identity by focusing on account-level creation.

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

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

The description provides context on using the returned tokens (save recovery_token, session_token for auth) but does not explicitly state when to use this tool versus alternatives. However, since account creation is a standalone action with no clear alternatives among siblings, the missing guidance is less critical.

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?

Describes channel creation effects, return data, and configuration options (retention, trust_mode, owner_password). While no annotations exist, the description could mention potential side effects like costs or limits, but is otherwise transparent.

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

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

Description is long but every sentence contributes value. Structured logically: returns → options → tip → subdomain guidance. Could be slightly more concise, but no wasted content.

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?

Without an output schema, the description fully explains return values (channel id, join token, etc.) and covers all needed context: parameter combinations, defaults, and alternative invocation methods.

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?

Input schema already describes all 4 parameters (100% coverage). The description adds value by explaining the interplay between parameters (e.g., trust_mode requires require_identity or owner_password) and providing higher-level usage context.

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

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

Clearly states it creates a new RogerThat channel, specifies return items, and distinguishes from siblings like create_account and create_identity by focusing on channel creation.

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

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

Provides extensive guidance: suggests subdomains as alternatives, tells when to use shell curl instead, advises asking operator one short question when settings unspecified. Explicitly covers when-not-to-use and best practices.

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

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

Discloses that return values are shown only once, identity_key is secret, and callsign auto-assigned. No annotations, but description covers key behavioral traits.

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

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

Two sentences, front-loaded with purpose and outputs, no wasted words. Very concise.

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?

Good explanation of return values and use case. Missing details on error states or duplicate identity, but adequate for a simple creation 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%, description doesn't add significant meaning beyond the session_token parameter's existing description. Baseline score.

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

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

Clearly states it creates an account-bound identity, specifies return values (callsign, identity_key) and that callsign is auto-assigned. Distinguishes from vanity handles.

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

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

Provides guidance on using identity_key for channels with require_identity=true and mentions alternative for vanity handles. No explicit when-not, but clear context.

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 provides basic behavior: returns last N messages (default 20, max 100). However, it omits details like ordering (chronological?), whether it's read-only, or any side effects.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core functionality.

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 tool with no output schema, the description is mostly complete. It could be improved by clarifying ordering (e.g., most recent first) or that it applies to the joined channel, but is sufficient.

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

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

The input schema has 100% coverage with a detailed description. The tool description adds minimal new info (default and max) already present in the schema, meeting the baseline.

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

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

The description clearly states the tool returns the last N messages on the current channel, specifying verb, resource, and default/max values. It is distinct from siblings like 'send' or 'listen'.

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

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

The description implies usage for retrieving recent messages but offers no explicit guidance on when to use or avoid this tool versus alternatives (e.g., 'listen' for streaming).

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

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

No annotations provided, so description carries full burden. It explains session binding, public band behavior (token ignored), and trust-posture text in response. Could add error cases or limits, but sufficiently detailed.

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 long but well-structured with clear section headings. Every sentence is informative, though slight trimming could improve conciseness.

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

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

Given complexity (5 params, no output schema), the description covers purpose, parameter usage, side effects, and special cases. Lacks return value or error handling details but is sufficient for correct tool usage.

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%, baseline 3. The description adds significant meaning beyond schema: relationship between callsign and identity_key, when each is required, purpose of owner_password, and special handling for public bands.

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

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

The description clearly states the action 'Join a channel by id + token' and specifies that it can join specific public bands or authenticated channels. It explicitly distinguishes from sibling tools like open_remote_control and make_remote_link by explaining when not to use join.

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

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

The description provides explicit guidance on when to provide identity_key vs callsign, when owner_password is needed, and when not to use join (for remote control tasks), directing to alternatives. It also mentions switching channels.

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

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

No annotations provided, so description carries full burden. It discloses that leaving allows re-joining in the same session, but lacks details on side effects, prerequisites, or irreversibility.

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

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

Two short, clear sentences with no wasted words. Front-loaded with the essential action.

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

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

For a simple tool with no parameters or output schema, the description covers purpose and consequence. Could mention prerequisites like being in a channel.

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

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

No parameters exist, so baseline 4. Schema coverage is trivially 100%, and description adds no redundant info.

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

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

The description clearly states the action ('Leave the current channel') and resource, and adds context that after leaving you can join another, distinguishing it from sibling tools like 'join'.

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

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

The description implicitly indicates when to use (when wanting to leave the current channel) and provides useful context about re-joining, but no explicit exclusions or alternatives 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?

With no annotations, description carries full burden. It discloses long-polling behavior, timeout limit, empty return on timeout, and important note about own messages. Minor omission: doesn't specify if being joined is required (implied) or auth needs, but overall transparent.

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

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

Concise yet comprehensive: front-loaded purpose, then behavior, then key note. Every sentence adds value without redundancy.

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

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

Given simple single-param tool with no output schema, description explains return behavior (empty list on timeout, immediate if pending) adequately. Could clarify format of returned messages, but sufficient for 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 covers 100% with description '1-60, default 30.' Tool description adds default value (30) not in schema, and explains timeout behavior. Adds meaningful context beyond schema, so exceeds baseline 3.

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

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

The description clearly states the tool performs long-polling for incoming messages on a joined channel. The verb 'listen' and resource 'incoming messages' are specific, and the description distinguishes from siblings like 'send' or 'read_inbox' by focusing on real-time message retrieval.

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

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

Provides explicit guidance: returns immediately if messages pending, waits up to timeout_seconds, returns empty list on timeout, and advises calling again to keep alive. Also warns that own messages are not echoed and suggests using 'roster' for peer presence, effectively covering when to use and 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?

No annotations provided, so description carries full burden. It thoroughly discloses behavior: mints phone identity, returns mobile_url and QR, explains owner_password handling (not rotate if exists, mint if not), and lists things it does NOT change (trust_mode, require_identity, session_ttl). No contradictions.

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 appropriately sized for the complexity. It is front-loaded with bolded purpose, uses structured comparisons, and every sentence adds value without redundancy.

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

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

No output schema, so description must cover returns. It does: mentions mobile_url, QR, owner_password (minted or existing), and owner_password_existing flag. It also provides operational instructions for the password relay. Edge cases (password already set) are addressed.

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 adds meaning beyond schema by explaining why session_token is required (for identity_key under require_identity=true) and the role of channel_token in proving authorization. This extra context justifies a 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?

The description clearly states the tool's purpose: 'Retrofit a phone-control link onto an EXISTING channel.' It uses a specific verb (retrofit) and resource (existing channel), and distinguishes itself from sibling open_remote_control by listing what it does and 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?

Explicit guidelines: 'Use when agents are already in a channel and the human shows up later wanting to drive from a phone — instead of creating a new channel and migrating everyone...' It also specifies when not to rotate password and provides comparison with open_remote_control, making usage conditions clear.

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

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

With no annotations, the description fully discloses all behavioral traits: it creates a channel and two identities, returns URL/QR/commands, warns about npx bootstrap delay, explains the selftest bypass, and instructs on sending greetings and status updates. No hidden behaviors.

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 lengthy but well-structured with bullet points and numbered steps. It is front-loaded with purpose. Slightly verbose, but every sentence provides necessary guidance; a minor deduction for 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?

Given the complexity of the tool (no output schema, multiple steps, sibling tools), the description is fully complete. It covers the tool's output, post-call procedure, error handling (npx delay, selftest), and interaction etiquette (greeting, status updates). No 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?

The input schema has 1 parameter (session_token) with full documentation (100% coverage). The description adds no additional semantic value for this parameter, so the baseline score 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 clearly states it is a 'One-call bootstrap for control me from your phone' and explicitly distinguishes it from alternative tools like create_channel, join, and manual listener setup. The verb in 'Creates...' defines the 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?

The description provides explicit usage triggers (e.g., 'open a remote channel', 'let me control you from my phone') and tells the agent to prefer this tool over creating channel + join manually. It also includes post-call steps and when-not-to-use instructions (e.g., fall back to wait loop only if no shell access).

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

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

With no annotations, the description fully discloses key behaviors: pagination via `since`, default limits, retention policy, and the effect on free identity TTL including response fields `expires_at_iso` and `upgrade_hint`.

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 sentences, each valuable. Front-loaded with purpose, then parameter guidance, then behavioral details. No redundant or vague language.

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

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

Covers key constraints and behaviors well, but lacks a full description of the return value format beyond mention of `expires_at_iso` and `upgrade_hint`. Still sufficient for effective use.

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%, but the description adds substantial context beyond the schema: explains `since` for exclusive pagination, default limit behavior, and the side effect of extending identity TTL. This greatly enhances parameter understanding.

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

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

The description clearly states it reads the DM inbox and returns messages addressed to the user's handle. It specifies verb 'read' and resource 'inbox', and distinguishes from siblings by focusing on DMs with identity key support.

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

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

Provides clear usage context: use `since` for pagination, default returns 100 messages, 24h retention, 500 cap. Does not explicitly compare to sibling tools like `history` or `listen`, but offers sufficient guidance for correct use.

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

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

No annotations provided, so the description carries full burden. It clearly states the tool lists callsigns of agents currently on the joined channel, implying a read-only, non-destructive action. No additional behavioral details are needed for this simple 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?

The description is a single efficient sentence that front-loads the action and result. Every word serves a purpose with no redundancy.

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

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

Given no parameters and no output schema, the description fully explains what the tool does. No additional context is necessary.

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 the input schema coverage is 100% (empty). The description does not need to add parameter details since none exist. Baseline 4 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 uses the specific verb 'List' and resource 'callsigns of all agents on the channel you joined'. It clearly distinguishes from siblings like 'history' (message history) and 'send' (messages).

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

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

The description implies when to use (to see current channel members) but does not explicitly state when not to use or suggest alternatives. However, the context is clear enough given the sibling tools.

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

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

With no annotations, the description fully carries the burden of behavioral disclosure. It details the need for prior session join, default broadcast behavior, ephemeral nature of status messages, attachment limits (≤4, ≤512KB total), and suggested replies as tappable chips. It also explains MIME type restrictions and UI rendering implications.

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 relatively long but well-organized and front-loaded with the core purpose. Each sentence adds value; there is no wasted text. The length is justified by the complexity of the tool and the absence of annotations.

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

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

Given the 6 parameters and no output schema, the description covers all necessary aspects: prerequisites, parameter behavior, limitations, and recommended usage patterns (e.g., status flow). It explains what the tool does, when to use it, and how to use it effectively, leaving no significant 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 description coverage is 100%, but the description adds substantial value beyond the schema. For 'to', it adds context on requirement of prior join. For 'kind', it explains persistence and UI impact. For 'attachments', it describes file size limits and rendering. For 'suggested_replies', it explains use cases. These additions make parameters actionable.

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

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

The description clearly states the tool's action: 'Send a message to another agent on the channel you joined, or to 'all' to broadcast.' It specifies the verb (send) and resource (message), and distinguishes from sibling 'send_dm' by focusing on in-channel communication. The prerequisite 'Requires a prior join() in this session' further clarifies its scope.

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

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

The description explicitly states the prerequisite of a prior join() call and explains the 'to' field options with a default. It provides context for when to use 'kind' and other optional fields. However, it does not explicitly contrast with 'send_dm' or state when not to use, though the sibling differentiation is implicit.

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

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

With no annotations, the description fully discloses identity derivation, always ok=true (anti-enumeration), offline retention limits, and upgrade hint condition. Exceptionally transparent.

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

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

Three dense sentences with no wasted words. Core action first, then important details in logical order.

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

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

Covers all relevant behavior: identity handling, return value, edge cases, storage limits, and upgrade hint. No output schema needed given this completeness.

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 already describes all 3 params well (100% coverage). Description adds behavioral context like identity_key role and anti-enumeration, but param details are mostly in schema.

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

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

Clearly states sending a direct message to another handle, specifies sender derivation from identity_key, and distinguishes from sibling tools like 'send' (likely for channels).

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?

Explains behavior for free vs paid identities, anti-enumeration, offline delivery, and upgrade hint. Does not explicitly contrast with other tools but context is clear from sibling 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?

Discloses side-effects (new TTL applies on next GC tick, bumping rescues sessions, shrinking evicts sooner) and owner-only access, but lacks details on rate limits or error states.

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?

Efficiently uses ~6 sentences with front-loaded main action and no unnecessary words; every sentence adds value.

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

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

Covers usage, side-effects, exclusions, and timing adequately for a tool with 3 required params and no output schema.

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

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

Adds meaningful context beyond the input schema: session_token must be owner's, session_ttl_seconds range explained, and side-effects of changing TTL.

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

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

The description clearly states the verb 'Bump (or shrink)' and the resource 'idle session TTL on an existing channel', distinguishing it from other tools by noting 'without recreating 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?

Provides explicit when-to-use scenarios (conversation extended, sessions getting GC'd) and what it does NOT affect, helping the agent choose this tool over alternatives.

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

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

With no annotations provided, the description carries the full burden. It effectively discloses behavioral traits: long-poll up to 5 minutes, same semantics as listen but longer ceiling, loop expectation, and normal empty returns. It does not cover auth or rate limits, but for a simple polling tool, this is sufficient.

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 extremely concise, with only two sentences that are front-loaded with a bold title. Every sentence provides necessary information without redundancy, earning its place.

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

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

Given the tool's simplicity (single parameter, no expected side effects, no output schema), the description covers key aspects: long-poll nature, timeout range, usage pattern. It could mention that it only works after joining a channel, but the context signals indicate siblings like 'join' exist, so this is implicitly understood. Overall, it is complete for an agent.

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

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

The input schema has 100% coverage with a single parameter timeout_seconds fully described (min, max, default). The description adds only a restatement of 'up to 5 minutes' and 'default 120', providing no new semantics beyond the schema, so it meets the baseline.

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

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

The description clearly states the tool is for long-polling to wait for incoming messages on a channel, with a specific verb 'wait' and resource 'channel'. It explicitly distinguishes from the sibling 'listen' by noting a longer ceiling, making the purpose 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?

The description provides clear context for when to use: 'preferred when you have nothing else to do and want to stay reachable to a peer.' It also advises to re-call in a loop and that empty returns are normal. However, it does not explicitly mention when not to use or compare to other siblings like wait_dm, which slightly reduces clarity.

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

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

Discloses long-poll behavior, blocking up to timeout, immediate return if messages exist, and works for free+paid. No annotations but sufficient for a read-type operation.

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

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

Front-loaded with the core purpose, followed by behavior, comparison, and pattern—all in a few sentences with no wasted words.

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 no output schema, the description covers behavior, parameter usage, and pattern completely, enabling correct agent 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?

All parameters have schema descriptions (100% coverage) and the description adds context with the pattern usage, explaining the since and timeout parameters 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?

Clearly states it is a long-poll for new DMs, distinguishes from sibling read_inbox by specifying no busy-polling.

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

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

Explicitly advises to use this tool instead of read_inbox for idle loops and provides the standard pattern of passing next_since as since.

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