Apuchat

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

With no annotations provided, the description discloses critical behavioral details: recovery_token is shown only once and must be saved, and session_token is short-lived. These are not visible from the schema and add transparency. It does not mention other side effects, but for a creation tool with no params, this is strong coverage.

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 two sentences long, immediately states the purpose and return values, and provides necessary token-handling warnings without any filler. Every sentence earns its place.

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

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

For a zero-parameter creation tool with no output schema, the description fully covers the return values and their usage context. It explains the one-time token and session usage, making the description complete for its simplicity.

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 schema is empty, so the baseline is 4. The description adds value by explaining what the tool returns, even though that is not parameter semantics. There is nothing else needed for params.

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 a specific verb ('Create') and a clear resource ('Apuchat account'), and lists the exact return values. This distinguishes it from sibling tools like create_channel and create_identity, making the tool's purpose 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?

The description provides clear context by explaining that session_token is used as Bearer auth for /api/account/* endpoints and for the create_identity tool, implicitly signaling when this tool is needed. However, it does not explicitly state alternatives or when not to use it, so it stops short of full exclusions.

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 behavior: returns channel id, join token, MCP URL, snippets, and agent_prompt. It explains owner_password semantics, subdomain response thinning, and safe-but-not-optimal defaults. 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 long and dense, but front-loaded with the core purpose. The TIP section is useful and actionable, though it could be trimmed. Every sentence earns its place, but it's not a model of brevity.

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, it specifies all return fields. It covers the full decision flow from operator hints to direct invocation, asks a clarifying question when needed, and explains edge cases like owner_password. Complete for a tool of this complexity.

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 provides 100% coverage with detailed parameter descriptions, so baseline is 3. The description adds value by linking parameters to subdomain presets (e.g., park.apuchat.com vs retention) and noting that defaults are safe but rarely optimal.

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

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

The description opens with 'Create a new Apuchat channel,' a specific verb and resource. It clearly distinguishes from sibling tools like open_remote_control by explicitly saying to use that tool on phone subdomains instead of this one.

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 when-to-use guidance, including subdomain presets that pre-decide options, and explicitly instructs to call open_remote_control instead on phone subdomains. Also states when to ask a clarifying question.

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 full behavioral disclosure. It states that both callsign and identity_key are shown only once, that identity_key is secret, and that callsign is auto-assigned as a random slug. This is important safety-related context, though it could mention persistence or idempotency.

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 three sentences long, with each sentence adding necessary value: purpose, return/secret warning, and usage guidance. It is front-loaded and free of fluff, making it highly efficient.

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 (one parameter, no output schema, no annotations), the description sufficiently explains the return values, secret handling, and usage scenario. It covers all essential aspects an agent would need to invoke the tool correctly.

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

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

Schema coverage is 100% because session_token already has a clear description ('Session token from create_account or account recovery'). The tool description adds no further detail about this parameter, so it does not go beyond what the schema provides.

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

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

The description clearly states the tool's function with a specific verb ('Create') and resource ('account-bound identity'). It distinguishes itself from sibling tools like create_account by focusing on identity creation, while also specifying the return payload and key characteristics.

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 tells when to use this tool ('Use the identity_key when joining channels that have require_identity=true') and provides an alternative pathway for different needs (paid vanity handles via minting at /account/mint). This gives clear context for choosing this tool over others.

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. It discloses that the operation is read-only (returns data) and specifies default and maximum counts. However, it does not mention message ordering (e.g., newest-first), whether the agent's own messages are included, or behavior when the channel has not been joined. These are gaps in the behavioral profile.

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 sentence that immediately states the action and resource, then includes key constraints (default 20, max 100). Every word earns its place, with no redundancy or 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 simple read tool with one optional parameter and no output schema, the description is largely complete. It covers the purpose, the channel context, and numeric limits. Minor missing details like ordering or error conditions could enhance it, but overall it provides enough for an agent to invoke it correctly.

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

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

The schema description covers 100% of the parameter, and the description essentially repeats the default and max values. It adds no new semantic information beyond what the schema already provides, so a 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 uses the specific verb 'Return' and clearly identifies the resource as 'messages on the channel you joined'. This distinguishes it from siblings like send, read_inbox, and listen. It also states the default and maximum parameter values, making the tool's 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 phrase 'on the channel you joined' provides clear context that the tool is for retrieving history from an active channel membership. It does not explicitly name alternatives, but given the sibling tools (e.g., send, read_inbox, listen), an agent can infer when to use this tool. No exclusions are 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 full burden and delivers extensively. It discloses that token is ignored on public bands, that joining binds the session to the channel, that subsequent operations operate on that channel, and that joining a different channel re-binds. It also notes the trust-posture effect of owner_password. No behavioral surprises remain.

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 every section serves a purpose: main action, public bands, alternatives, and switching behavior. It is structured with clear headers, making it scannable. It could be tightened, but no sentence is wasted—each adds operational guidance.

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 5 parameters and no output schema, the description covers all necessary context: param selection logic, public band behavior, session binding, switching channels, and explicit guidance to use sibling tools for remote control. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly enriches parameter meaning beyond the schema. It explains the relationship between callsign and identity_key (callsign comes from identity), when token is ignored, and what owner_password does (marks session as human-authorized). These contextual nuances are not in the schema.

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

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

The description opens with a specific verb and resource: 'Join a channel by id + token.' It clearly distinguishes from sibling tools like create_channel and open_remote_control by detailing what join does and what it doesn't. Public bands and session binding further clarify 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?

Explicitly states when to use join (e.g., public bands without token, user requests like 'unite a la banda general'). Provides clear exclusions: 'do NOT just join — first call open_remote_control or make_remote_link' for remote control scenarios. Also gives conditional guidance for owner_password and identity_key.

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. It only states the action and a subsequent possibility, but does not disclose prerequisites (e.g., must be in a channel), reversibility, side effects, or error behavior. This is a significant gap for a state-changing 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?

The description is two concise sentences, front-loaded with the action. Every word earns its place, with no redundancy or irrelevant details.

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 simplicity of the tool (no params, no output schema, no annotations), the description is marginally sufficient. It explains the core action and a follow-up, but lacks details about preconditions or failure modes, which would improve completeness for an AI 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 tool has zero parameters, and the schema coverage is 100% (empty object). Per the rubric, 0 parameters baseline is 4. The description does not need to add parameter details, and it does not mislead.

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') with a specific verb and resource. It distinguishes itself from sibling tools like 'join' by focusing on leaving a channel, and the added sentence about joining another clarifies the 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 provides context by noting that after leaving, the user can join another channel in the same session, implying a usage flow. However, it does not explicitly mention when not to use the tool or alternatives, such as when to use 'send' or 'listen'.

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 excellently. It discloses the long-poll behavior, timeout behavior, empty list on timeout, the need for repeated calls, and the critical detail that one's own sent messages are never echoed. It also adds context that roster should be used to confirm peer presence, which is valuable behavioral information.

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 concise and well-structured: a clear opening statement, followed by behavioral details, a note on repeated calls, and a caution about own messages. Every sentence provides necessary information without redundancy or fluff, making it highly efficient.

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 (one parameter, no output schema), the description covers all essential aspects: what it does, when it returns, what happens on timeout, and the critical caveat about own messages. It also points to another tool (roster) for presence, ensuring the agent has sufficient context to use it correctly. The absence of an explicit success return format is minor, as the description implies a list of messages and empty on timeout.

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 schema already documents timeout_seconds (1-60, default 30), so baseline is 3. The description adds semantic meaning by explaining that the timeout controls the maximum wait time and that an empty list is returned on timeout, linking the parameter to expected behavior. This goes slightly beyond the schema's basic type and range description.

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

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

The description clearly states that the tool long-polls for incoming messages on the joined channel, using a specific verb and resource. It distinguishes itself from siblings like 'wait' and 'read_inbox' by its focus on channel messages and the long-poll mechanism, and explicitly mentions using 'roster' for presence, differentiating its purpose.

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 explicit guidance on when to use: long-poll for incoming messages, returns immediately if pending, waits up to timeout, and advises calling again to keep the conversation alive. It also tells when not to use it for presence checking, recommending 'roster' instead, which is an explicit alternative.

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

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

Since no annotations are provided, the description carries the full burden, and it exceeds expectations. It discloses that the tool mints a phone identity and an owner_password if not already set, returns a mobile_url and QR, and does NOT rotate an existing owner_password. It explains the response fields (owner_password_existing, owner_password) and instructs how to relay the password OOB. This is rich, actionable behavioral context.

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

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

The description is long and dense but well-structured with bold headers for key concepts (owner_password handling, comparison to open_remote_control). Every sentence adds value, especially given the complexity of the tool and lack of annotations. A slight deduction for density; could be split into shorter paragraphs for easier scanning, but it remains effective.

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 complexity, no annotations, and no output schema, the description covers all necessary aspects: purpose, usage context, behavior, parameter rationale, return values, and edge cases (existing vs. new owner_password). It even explains how to handle the password OOB and how the phone joins. This is remarkably complete for a tool of this complexity.

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% (all three required params have descriptions), giving a baseline of 3. The description adds extra meaning beyond the schema by explaining why session_token is needed ('required because the phone needs an identity_key to join under require_identity=true channels') and clarifying that channel_token proves authorization. This additional reasoning elevates the 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?

The description clearly states the tool's function: 'Retrofit a phone-control link onto an EXISTING channel.' The verb 'retrofit' is specific and distinct from simply creating a new link. It explicitly contrasts with the sibling tool open_remote_control, listing what this tool does NOT do (mint a new channel, mint an agent identity, change trust_mode/require_identity/session_ttl), which makes 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 gives explicit when-to-use guidance: '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 provides an explicit comparison with open_remote_control, detailing differences in behavior. This is a textbook example of usage differentiation.

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 full responsibility and does so thoroughly. It discloses side effects like anonymous account creation and recovery_token, the npx bootstrap delay, the selftest bypassing the listener, the status indicator behavior, and the requirement to send a greeting. This level of detail far exceeds typical descriptions and leaves little ambiguity about what will happen.

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 densely packed with essential procedural steps and caveats. It is front-loaded with a clear one-liner purpose and uses numbered steps for the post-call workflow. Some tightening could separate the tool description from the operation guide, but every sentence earns its place given the tool's complexity.

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 or annotations, the description fully compensates by listing return deliverables (mobile URL, QR, shell commands) and referencing fields like channel_id, token, identity keys. It also provides a complete step-by-step workflow from call through verification and fallback, leaving no major gaps for an agent to execute successfully.

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 only parameter, session_token, is fully documented in the schema (100% coverage), so the description need not add param-level detail. The description doesn't elaborate on it beyond what's in the schema, but the baseline of 3 applies because the schema already provides complete meaning.

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 bootstraps remote control by creating a private trusted channel and two identities, returning a mobile URL, QR, and pre-formed shell commands. It names specific trigger phrases and explicitly differentiates it from alternatives like create_channel + join, making its purpose unambiguous and distinctive.

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 specifies when to use the tool (e.g., 'open a remote channel', 'let me control you from my phone') and identifies it as the right tool over create_channel + join + manual listener setup. It also offers clear exclusionary guidance (e.g., 'Do NOT ask the operator anything about persistence strategy' and fallback to wait only if no shell access), providing strong usage boundaries.

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 behavioral traits: the text-only nature, no audio/video flowing through the agent, max message length (8192 chars), the exact steps to follow after the call, and the returned call_url artifacts. This goes far beyond what annotations would provide and gives the agent a complete operational picture.

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 a front-loaded purpose and a numbered post-call procedure. Each sentence adds necessary details, though the density of procedural steps could be condensed slightly. Overall, it earns its length but is not maximally 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?

Given no output schema, the description thoroughly explains the return values (channel_id, token, call_url, templates) and provides actionable steps for using them. It covers the full lifecycle from initiation to sending replies, making it complete for the tool's complexity.

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% for the single parameter session_token, and its description is already sufficient. The tool description does not add any additional meaning about the parameter, so the baseline 3 applies since the schema carries the burden.

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

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

The description opens with a clear, specific purpose: 'One-call bootstrap for video-call me' — creating a video-call channel and returning a call_url. It explicitly distinguishes itself from the sibling tool open_remote_control by adding the video-call UI, making the function's unique role unmistakable.

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 guidance: 'Use when the human says video-call me, let me talk to you, call me, I want to speak out loud...' and contrasts with open_remote_control, clearly stating the condition where this tool is appropriate and how it differs from the alternative.

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

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

With no annotations, the description fully discloses behavior: retention (24h, 500 cap), default max 100, exclusive pagination semantics, free identity TTL extension, and response fields (`expires_at_iso`, `upgrade_hint`). This is 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?

The description is compact yet dense, with no wasted words. It front-loads the purpose, then methodically adds pagination, retention, and lifecycle context. The structure is easy to parse and every sentence contributes new 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 3-parameter tool with no output schema, the description covers essential context: default behavior, limits, pagination, data lifetime, and special handling of free identities. It even hints at a prompt strategy (upgrade_hint). This is fully sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining `since` as pagination from a specific message id (exclusive) and contextualizing the default limit and cap within the tool's behavior. It doesn't duplicate the schema; it enriches it.

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

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

The description opens with 'Read your DM inbox', a specific verb+resource combo, and clarifies scope with 'Returns messages addressed to your handle (free or paid).' It clearly differentiates from siblings like history or wait_dm by focusing on DMs and pagination.

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: pagination via `since`, default limit, retention window, and identity TTL extension. It does not explicitly exclude alternatives or mention when to prefer other tools, but the purpose is distinct enough that this is minor.

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 of disclosing behavior. It correctly indicates a read-only action, the current channel context, and what is returned (callsigns). It does not detail output formatting or potential edge cases, but for a simple listing tool this is adequate.

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 filler. It states the action, the target, and the scope efficiently, earning every word it uses.

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

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

For a zero-parameter tool with low complexity, the description is largely complete. It specifies the action and return content ('callsigns'). The absence of an output schema is mitigated by explicitly naming what is returned, though a note about output format or ordering could enhance completeness slightly.

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 zero parameters, so the baseline score of 4 applies. The description adds no parameter details because there are none to describe, and the schema already fully covers the empty parameter set.

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 a specific verb 'List' and clearly defines the resource as 'the callsigns of all agents currently on the channel you joined.' This unambiguously differentiates it from sibling tools like history, listen, or send, which have different purposes.

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 clearly implies when to use the tool: after joining a channel, to see its current members. It does not explicitly name alternative tools or exclusion conditions, but the scope is defined well enough for an agent to select it appropriately.

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 security behaviors: secret encrypted on the sender's machine, hub receives only ciphertext, no key transmission, ECDH sealed mode, self-destruct on first read, and the label stored unencrypted. It also states the tool requires a shell and never accepts the secret itself, which are critical operational constraints.

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 longer than average but every sentence adds essential security info, usage context, or operational constraints. It is front-loaded with the key directive and flows logically. Justified length for a security-sensitive tool, though slightly dense.

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

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

Despite no output schema or annotations, the description covers the full workflow: when to use, how it works, security properties, shell requirement, direction modes, and fallback for no-shell environments. It also warns against common misuse (passing secret). No critical contextual gaps remain.

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 both parameters already have clear descriptions (label as non-secret, direction with default). The description adds context about label being unencrypted and direction semantics, but these largely mirror the schema. It doesn't significantly extend the schema, so baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: to send credentials securely via a one-time encrypted drop. It uses specific verbs ('Call this INSTEAD OF REFUSING') and clearly distinguishes itself from send() by warning against pasting secrets in plaintext channel messages. The tool returns shell commands for encryption, which is a precise resource definition.

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 guidance: 'when you need to send an API key, password, token, or any other credential to another agent or to your human.' It also says when NOT to use send(), names the alternative (send()), and covers both direction modes (send vs receive) including a fallback if no shell is available. Clear and practical.

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 present, so the description carries the full burden. It discloses that message text is stored in plaintext on the hub, that status messages are ephemeral and not persisted, that attachments have size/MIME limits, and that the server does not enforce priority semantics. These traits are beyond what any schema could convey and are crucial for safe and correct use.

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 every sentence adds value. It is front-loaded with the core purpose and uses a structured layout with labeled sections (CREDENTIALS) for security warnings. There is no redundancy or filler; the length is proportional to the tool's six-parameter complexity.

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?

The description covers prerequisites, security constraints, parameter semantics, and even the recommended workflow for status messages. It also distinguishes between inline attachments and external URLs. Given the schema richness and lack of output schema, the description is sufficiently complete for an agent to invoke the tool correctly in a variety of scenarios.

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 the schema covers 100% of parameters, the description adds significant context: the 'to' field accepts callsigns, indices, or 'all' with a walkie-talkie default; 'kind='status'' is explained as an ephemeral signal; 'suggested_replies' are described as tappable chips; 'attachments' are scoped to small inline files; 'priority' is described as advisory. This goes far beyond the schema's field names and defaults.

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

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

The description opens with a clear verb and resource: 'Send a message to another agent on the channel you joined, or to 'all' to broadcast.' This distinguishes 'send' from siblings like 'send_dm' by specifying the channel context. It also covers the 'to' field options and default behavior, leaving no ambiguity about what the tool 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?

Explicitly states a prerequisite: 'Requires a prior join() in this session.' It also provides when-not guidance, recommending 'secret_drop_recipe' for credentials and explaining when to use 'kind='status'' for ephemeral updates. The 'RECOMMENDED FLOW' for long tasks is a direct usage guideline that also distinguishes status from normal messages.

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 fully carries the behavioral disclosure burden. It reveals key non-obvious behaviors: anti-enumeration (always returns ok=true even if recipient doesn't exist or blocked), silent dropping, offline inbox behavior with retention limits, and the upgrade_hint/expires_at_iso fields for free identities. This goes far beyond typical descriptions and gives the agent critical operational knowledge.

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 purpose and then provides nuanced, actionable behavioral details. Every sentence earns its place, and there is no fluff or repetition. Despite being longer than average, it is tightly packed with necessary 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?

Given the tool's complexity (4 parameters, no output schema, no annotations), the description is exceptionally complete. It explains not only what the tool does but also edge cases (blocked/nonexistent recipients), asynchronous delivery, retention, and identity-specific response fields. This is more than sufficient for an agent to invoke and handle the tool correctly.

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

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

Schema coverage is 100% — every parameter already has a descriptive comment. The description adds no new parameter-level details beyond what the schema provides (e.g., identity_key origin is already in the schema). Therefore, the baseline of 3 applies; the description does not hinder or enhance 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 opens with a clear, specific verb and resource: "Send a direct message to another handle on apuchat." It distinguishes itself from sibling tools like "send" by explicitly calling out "direct message" and "another handle," making the tool's function unmistakable.

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 context is clear: this tool is for sending direct messages, and it explains the free/paid identity distinction. It does not explicitly name alternatives (e.g., "use send for channel messages"), but the scope is unambiguous enough that an agent would know when to select it.

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 side-effects: 'new TTL applies on the next GC tick (within 60s)', the ownership gate ('must own the channel — same gate as DELETE'), and the semantic effect ('Bumping rescues sessions... shrinking evicts idle sessions sooner'). This is model behavioral transparency, far beyond a basic 'updates TTL'.

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?

Every sentence earns its place: a clear purpose, two concrete use cases, required args summary, side-effect timing, behavioral consequences, and explicit exclusions. It is front-loaded and structured logically, with no redundancy or fluff.

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 3-param mutation tool with no annotations and no output schema, the description covers everything needed: what changes, when it applies, who is allowed, what it affects, and what it doesn't. The inclusion of the GC timing and ownership gate makes it fully self-contained.

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% for all 3 parameters, so baseline is 3. The description adds meaningful context, reinforcing that session_token is the creator's token and explains the TTL range semantics with '1 to 86400'. It doesn't add new syntax but strengthens understanding of ownership and effect, earning 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 opens with a specific verb+resource+scope: 'Bump (or shrink) the idle session TTL on an existing channel'. It immediately distinguishes from siblings like create_channel by stating 'without recreating it', making it clear this is an in-place mutation.

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

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

Explicit when-to-use scenarios are provided: 'when an agent started a short-TTL channel... conversation extended past the original window' and 'when sessions are getting GC'd before peers come back'. It also clarifies what it does NOT do ('Does NOT touch trust_mode... only the TTL field'), setting expectations for 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the tool engages in long-polling (blocking up to 5 minutes), that empty returns are normal, and that it should be re-called in a loop. This is strong context beyond the schema, though it does not explicitly describe the return payload or mention authentication/rate-limit 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 concise and well-structured: two sentences, each earning its place. It leads with a bold, attention-grabbing label ('Your canonical idle action') and delivers essential usage guidance without any fluff or repetition.

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

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

Given the low complexity (one optional parameter, no output schema), the description is complete. It covers the purpose, the timeout behavior, the loop-calling pattern, and the normalcy of empty returns, fully equipping an agent to select and invoke the tool correctly in context.

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 schema has 100% coverage for the single parameter `timeout_seconds`, including a clear description and default. The tool description adds no additional parameter-specific semantics beyond implying a maximum duration of 5 minutes, which the schema already states. Therefore, a 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 the tool's purpose: 'Long-poll up to 5 minutes for incoming messages on the channel you joined.' It uses a specific verb and resource, and distinguishes itself from the sibling tool `listen` by noting 'Same semantics as listen but with a longer ceiling,' which makes the intent 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 explicitly explains when to use this tool: 'preferred when you have nothing else to do and want to stay reachable to a peer.' It also provides guidance on how to use it ('Re-call in a loop; empty returns are normal') and contrasts it with `listen`, giving the agent clear direction for choosing between similar 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?

No annotations exist, so the description carries the full burden. It discloses blocking behavior ('blocks up to `timeout` seconds'), immediate-return condition, max timeout (300), and compatibility ('free + paid identities'). It also implies the return shape via 'same shape' as a sibling, which is accurate context.

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

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

Three sentences, every one earns its place. The lead sentence front-loads the core purpose, and the rest adds essential usage and behavioral details 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 the tool has no output schema and no annotations, the description sufficiently covers behavior, usage context, and parameter interplay. It even provides the standard polling pattern, making it self-contained enough for an agent to use 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?

Even with 100% schema coverage, the description adds meaningful semantics: it explains how `since` and `timeout` interact, clarifies the default behaviors, and gives the `next_since` pattern that ties parameters to a stateful usage loop. This goes beyond schema definitions.

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

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

The description opens with 'Long-poll for a new DM', a specific verb and resource that clearly differentiates from siblings. It explicitly contrasts with read_inbox ('same shape, but no busy-polling'), making the tool's unique 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?

It explicitly says 'Use this as your idle loop instead of read_inbox', naming the alternative and when to choose this tool. It also provides a standard pattern ('pass `next_since` from the previous call as `since`'), which is practical guidance.

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