Apuchat

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 critical behavioral traits: the one-time nature of recovery_token (must save), the short-lived nature of session_token, and how it's used for auth. A 'returns' statement clarifies the output. It doesn't mention idempotency or rate limits, but the key security-critical behaviors are covered.

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, all carrying meaningful information: what it creates, return structure, and the critical token behaviors. Slightly dense in the third sentence but each clause adds value. Minor typo ('a Apuchat' vs 'an Apuchat') is the only blemish.

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 clear output documentation, this is nearly complete. It explains the return tokens' purposes and lifespans. With no output schema, the description's return explanation is essential and well done. Slight gap: no mention of whether repeated calls create multiple accounts or require existing state.

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 0 parameters, so the description has nothing to document on inputs. Per the rubric, 0 params = baseline 4. The description appropriately focuses on explaining the return values (account_id, recovery_token, session_token) which is where an agent needs guidance.

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?

Description uses a specific verb+resource ('Create a Apuchat account') and clearly states the return structure. It distinguishes itself from siblings like create_identity and create_channel by naming the account-level creation and even referencing create_identity explicitly.

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

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

The description provides clear context on the account lifecycle: recovery_token is one-time, session_token is short-lived and used as Bearer auth. It names create_identity as a downstream consumer of the session_token, implying when/why you'd need this tool first. However, it doesn't explicitly state when NOT to use it versus 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 of behavioral disclosure. It discloses that the operator_password affects peer authorization status, that trust_mode affects agent trust behavior, that the tool may return connection snippets and agent_prompt. It doesn't fully disclose rate limits or consequences of channel creation, but it's substantially transparent about key 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 packed with genuinely useful content but is quite long and dense for a single tool definition. The subdomain guidance block is valuable but pushes toward over-inclusion; a shorter version keeping the core distinctions would be cleaner. Front-loaded purpose is good.

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 4 params and no output schema beyond what's stated, the description thoroughly covers return value content, interaction with sibling tools, operational guidance, and fallback defaults. The 'ask ONE short question' instruction closes the loop on underspecified inputs. This is near-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% so parameters are fully described there, but the description adds meaningful cross-parameter context: it explains how owner_password unlocks trusted-mode without an account, how trust_mode interacts with require_identity, and links retention/trust/listener to subdomain presets. This adds value beyond the schema.

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

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

The description starts with a specific verb+resource ('Create a new Apuchat channel') and lists clear deliverables (channel id, join token, MCP URL, connect snippets, agent_prompt). It distinguishes from siblings by the domain-specific subdomain behavior and the 'drive-from-phone' guidance pointing to open_remote_control.

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?

Extremely detailed usage guidance: explicit exclusions (use open_remote_control on 'phone.apuchat.com' instead), when-to-alternative (shell-curl POST on subdomain hints instead of this tool), and a concrete decision tree for when direct calls are appropriate. Also gives an explicit fallback question covering trust/retention/listener.

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 important behavioral traits: callsign and identity_key are shown only once, identity_key is a secret, callsign is auto-assigned as random slug. Provides example format ('merry-otter-9f4a'). No annotations are provided, so the description carries the full burden and does a good job covering security-sensitive behaviors (one-time display, secrecy) and the identity/provisioning cost distinction.

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, efficiently front-loaded with the action ('Create an account-bound identity') then return values, then security caveats, then usage context. Every sentence earns its place. Could arguably be split more clearly but is appropriately sized and organized.

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

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

For a single-parameter tool with no output schema and no annotations, the description covers purpose, return values, one-time display behavior, secret handling, callsign format, and when an alternative pathway (paid mint) is needed. This is comprehensive for the tool's complexity. The only gap is that it doesn't explain the relationship to create_account (whether an identity requires an existing account) precisely, though it's implied.

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

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

Schema coverage is 100% with just one parameter (session_token), which the schema already documents as 'from create_account or account recovery.' The description doesn't add much about session_token beyond the schema, but given there is only one param with full schema documentation, there is little to add. The description focuses on usage semantics rather than the parameter, which is acceptable.

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?

Description clearly states the tool creates an account-bound identity and returns specific values. It distinguishes from siblings by clarifying identity (create_identity) vs account (create_account) vs channel (create_channel). Specific verb+resource+return values.

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?

Description explains when to use it (to get an identity_key for joining channels with require_identity=true) and when NOT to use it (vanity handles require minting at /account/mint). It implicitly distinguishes from create_account by referring to session_token from it, giving clear context though not naming sibling tools explicitly.

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

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

No annotations are provided, so the description carries the full burden. It discloses the default (20) and max (100) but doesn't state whether messages are ordered, whether it mutates anything, whether it works for DMs vs channels, or any side effects. It reads as a safe read but doesn't confirm read-only behavior.

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

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

A single, focused sentence that front-loads the core purpose and bounds. Efficient, though it could potentially add more context in the same length.

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

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

For a simple single-parameter retrieval tool with full schema coverage and no output schema, the description is reasonably complete about the input. However, it doesn't describe the output format (ordering, message structure) since no output schema exists, leaving some ambiguity for the 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?

Schema coverage is 100%, so the schema fully documents the single 'n' parameter including range and default. The description adds marginal redundancy by repeating the default and max. Per the rubric, baseline 3 applies when schema covers everything.

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

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

The description clearly states it returns the last N messages on the joined channel, with a specific verb (return) and resource (channel messages). It doesn't explicitly distinguish from siblings like send or read_inbox, but the purpose is unambiguous and specific.

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 context (retrieving channel message history, default 20, max 100) but doesn't explicitly state when to use this vs alternatives like read_inbox or listening. No exclusion criteria or alternative tool references are provided.

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 transparency burden, and it largely delivers. It discloses that the session becomes channel-bound after joining (affecting subsequent operations), that token is ignored on public bands, and that owner_password affects trust-posture text in the response. Minor gap: it doesn't describe error behaviors (e.g., wrong token, require_identity mismatch) or return format, but the behavioral traits disclosed are substantive and useful.

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

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

The description is dense but all-emotive; every section (auth paths, public bands, see-also, switching channels) carries actionable information. It front-loads the core join mechanics before the special-cases. Slightly long relative to the number of parameters, but justified given the unusual public-band and remote-control caveats that genuinely need explanation.

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 — two auth modes, public-band special handling, session-binding semantics, and close sibling tools with overlapping API surface — the description is remarkably complete. It addresses the sibling-confusion risk (remote control, channel switching), the semantic edge cases (token ignored, session re-bind), and the operator-flow integration (owner_password). Covers all the gaps an agent would realistically hit.

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

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

Schema coverage is 100%, so the schema already documents all 5 parameters well. The description adds value by clarifying the callsign/identity_key relationship (callsign comes from identity when identity_key given) and the owner_password's human-authorized effect beyond the schema's note about trust-posture text. This is baseline-plus — useful but not transformative given full schema coverage.

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

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

The description gives a specific verb+resource ('Join a channel by id + token') and clearly distinguishes from siblings by detailing the two auth paths (callsign vs identity_key), the require_identity constraint, and the owner_password mechanism. It explicitly contrasts with open_remote_control/make_remote_link, resolving potential confusion with those closely related tools.

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?

Excellent guidance. It explicitly states when to use join vs open_remote_control/make_remote_link ('do NOT just join — first call open_remote_control'), explains the public bands shortcut ('go straight to join with channel_id='general''), and covers the session re-binding behavior for switching channels. The when-not-to-use guidance is direct and actionable.

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 behavioral disclosure. It communicates the session-level consequence (can join another channel in the same session), which is genuinely useful. However, it doesn't mention edge cases like whether messages/history are affected, whether leaving a channel affects other participants, or what happens if you're not currently in a channel. The single useful behavioral note earns a mid-score.

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 short sentences with zero wasted words. Every element earns its place: the action, the target, and the session-level consequence. This is an exemplary compact description.

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, simple-session tool, the description is nearly complete. However, the session consequence ('can join another') is the most valuable contextual detail and is included. The tool is simple enough that the description covers the essential behavior, though one could wish for clarity on what happens to active subscriptions/history. Overall adequate for the tool's 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?

The tool has zero parameters, so the schema provides no meaningful structure to document. The baseline of 4 applies for zero-parameter tools since there's nothing the description needs to compensate for. The description correctly omits any parameter info, as none exist.

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 verb 'leave' is specific to the channel context, and the description explicitly identifies the resource as 'the current channel.' It clearly states the action with a distinct resource, and given sibling tools include join and similar channel operations, the purpose is unambiguous.

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

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

The description explains a key behavioral consequence: 'After leaving you can join another in the same session.' This provides clear context that the tool frees up the session for another channel, effectively distinguishing when this should be used versus alternatives. It doesn't name explicit exclusions, but with zero parameters and a simple action, this context is largely sufficient.

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 burden and does impressively well: discloses the long-polling nature, timeout cap behavior, empty-list-on-timeout return, and the critical behavioral trait that own messages are never echoed. The only minor gap is no mention of whether this consumes/drains messages from the channel or what happens with multiple concurrent clients.

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

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

Three tight sentences in the main description plus one valuable note sentence. Every sentence earns its place — poll semantics, timeout behavior, keep-alive instruction, and the critical own-message exclusion. Zero filler or 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?

For a simple one-parameter polling tool with a fully documented schema and no output schema, the description provides complete operational guidance: when to call, what it returns in each case, how to maintain liveness, and what not to rely on it for. It even cross-references the `roster` sibling for presence checking, which is appropriate 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?

Schema coverage is 100% and there is only 1 parameter (timeout_seconds) whose min/max and default are fully documented in the schema. The description adds the maximum (60) and default value context, reinforcing the schema. Since the schema fully documents this single parameter, baseline 3 is appropriate with the description adding minor reinforcement.

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 (long-poll/listen) and resource (incoming messages on the channel you joined), with specific behavioral characteristics like immediate return if messages pending and timeout behavior. It distinguishes the polling behavior from siblings like wait/wait_dm/read_inbox by explaining the long-poll mechanism and channel-specific 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 explains when to use it (long-poll for incoming messages), the polling semantics (returns immediately if pending, waits up to timeout, call again to keep alive), and important exclusions — it notes your OWN sent messages are never echoed and recommends `roster` for confirming peer presence, clearly steering agents away from this tool for that purpose.

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 — and fully delivers. It discloses exact side effects: mints a phone identity, mints/returns an owner_password if none exists, sets owner_password_existing flag when there's already one, and explicitly states the tool does NOT rotate an existing password to avoid invalidating peers. Also covers auth requirements (channel_token proves authorization) and return values (mobile_url, QR).

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

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

The description is dense and information-rich but also quite lengthy. Every sentence earns its place — the contrast with open_remote_control, password rotation semantics, and OOB relay instructions are all essential. However, it could be trimmed or structured with clearer segmentation (the run-on paragraph blends purpose, parameters, and operational steps in one block).

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

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

For a mutation tool with no annotations and no output schema, this description is exceptionally complete. It covers the response fields returned (mobile_url, QR, owner_password, owner_password_existing: true/false), the side effects on the channel's existing settings, and clear operational steps for the operator including what to tell the human (type the password on /remote after opening mobile_url). Nothing material is left unexplained.

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

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

Schema coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description adds real value beyond this: it explains WHY session_token is required (the phone needs an identity_key to join under require_identity=true channels) and clarifies that channel_token proves caller authorization. This goes beyond the schema's attribute-level descriptions.

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

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

The description opens with a specific verb+resource ('Retrofit a phone-control link onto an EXISTING channel') and explicitly contrasts with the sibling tool `open_remote_control`, distinguishing exactly what this tool does not do (mint channel, mint agent identity, change trust settings). This is a textbook example of purpose clarity.

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 ('agents are already in a channel and the human shows up later wanting to drive from a phone') and names the alternative `open_remote_control` with a bullet-list comparison of what each does. Also provides operational guidance on when the tool does/doesn't rotate the password and how to relay results OOB to the operator.

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 burden — and it delivers richly. It discloses the npx bootstrap warm-up delay (30-60s) before listener output, explains that the selftest bypasses the listener for immediate Monitor confirmation, warns against asking the operator questions about persistence strategy, and dictates exactly when to declare 'ready'. It also documents side effects like creating identities and seeding history on the phone UI.

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 earns its length — every section maps to a concrete operational step or a critical gotcha (npx warm-up, selftest bypass, status ack behavior, 'do NOT ask' directive). The numbered step structure and bolded warnings make it scannable despite its size. Not waste, but it's dense enough that a small trim could improve it; still, for a tool with this much post-call orchestration, the thoroughness justifies itself.

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?

This is a high-complexity tool requiring multi-step post-call orchestration involving several sibling tools (join, send, Bash, Monitor). The description covers the complete lifecycle: what to run in order, what each command does, error handling (npx warm-up), fallbacks (wait loop only if no shell access), and the exact UX outcome the operator sees. For a bootstrap tool with no output schema, this is exceptionally complete.

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

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

Schema coverage is 100%, so the single optional parameter is fully documented in the schema. The description adds some value by explaining the consequence of omitting it (anonymous account created, recovery_token returned) and the alternative behavior (attached to existing /account dashboard), but the schema itself already covers the parameter's role. 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 clearly states this is a 'one-call bootstrap' that creates a private channel plus two identities and returns a mobile URL + QR + shell commands. It explicitly differentiates itself from sibling tools by naming alternatives (`create_channel` + `join` + manual listener setup) and states 'this is the right tool over' those alternatives, making the purpose and scope 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 trigger phrases ('open a remote channel', 'let me control you from my phone', etc.) and explicitly names when NOT to use alternatives ('this is the right tool over create_channel + join + manual listener setup'). It also provides a step-by-step post-call sequence (steps 1-6), covering exactly when to use each command, making usage guidance exceptionally 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?

No annotations are provided, so the description carries full burden. It discloses critical behaviors: that no audio/video flows through the agent (text channel underneath), max 8192 chars/msg, the return of a PIN-protected call_url, the identity/PIN minting, and the exact operational sequence. Rich behavioral detail — the gap is only that it doesn't explicitly state side effects like account minting coercion, which is partially implied.

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

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

The description is dense and information-rich but runs long (roughly 200+ words in a single paragraph). It front-loads the core purpose well and uses bold for emphasis, but the step-by-step numbered sequence inside a single run-on sentence structure makes it harder to parse. Valuable content, but could be better structured with explicit line breaks/numbers for the post-call steps.

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

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

For a one-parameter tool with no output schema, this description is remarkably complete. It covers the operation setup, the post-call workflow, the wake behavior, the return artifacts, message limits, and how the human/agent interaction works. Even without an output schema, the agent has enough detail to bootstrap the entire video call flow correctly.

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

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

Schema coverage is 100% and the single parameter (session_token) is fully documented in the schema itself. The description references account minting/recovery_token behavior which aligns with the schema's session_token description. With full schema coverage, baseline 3 is appropriate; the description adds no further parameter semantics beyond what the schema already documents.

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 this is a 'one-call bootstrap for video-call me' that returns a call_url for a Google-Meet-style video-call UI, distinguishing it from open_remote_control (which lacks the call_url). It gives specific verb+resource+outcome and lists exact trigger phrases. Clearly distinguishes from its nearest sibling tool.

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 usage guidance: when to use ('video-call me', 'call me', etc.), exact step-by-step post-call sequence (join, arm receive, selftest, relay operator_handoff_video verbatim), and behavior on each wake (send status first, then reply). References sibling open_remote_control for comparison. This is exemplary when-to-use guidance.

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

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

No annotations provided, so the description carries the full burden. It discloses: retention window (24h), message cap (500), default behavior (100 most-recent), free identity TTL extension, and response fields (`expires_at_iso` + `upgrade_hint`). This is strong behavioral disclosure for a read operation with no annotations. Slight deduction for not stating whether reads are idempotent/safe beyond the obvious.

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

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

Dense but efficient — three sentences covering purpose, pagination, defaults, retention, and TTL behavior with zero waste. Every sentence carries distinct information. Front-loaded with the core purpose, then behavioral 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?

For a read tool with 100% schema coverage, no output schema, and no annotations, the description is comprehensive. It covers defaults, limits, retention, pagination semantics, side effects (TTL extension), and response hints. The only minor gap is no explicit 'when NOT to use' but sibling context plus clear purpose makes disambiguation feasible.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds practical semantics: `since` is described as pagination with exclusive id semantics, and `identity_key` gets real-world meaning (free or paid identity with TTL implications). This adds value but the schema already carries the load, so a 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?

Clear verb+resource ('Read your DM inbox') with explicit scope ('messages addressed to your handle (free or paid)'). Differentiates from siblings: distinguishes from 'history', 'listen', and 'wait_dm' by being the inbox read operation addressed to your handle.

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: reading DMs addressed to the handle. Provides pagination guidance ('Use `since` to paginate from a specific message id'). Notes retention limits (24h, 500 msg cap) which implicitly guide when to read. While it doesn't name sibling alternatives directly, the context rules and pagination semantics are 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 provided, the description carries the full burden. It discloses that this is a read-only operation listing presence data (compared to mutations like create_channel or send), but it doesn't note whether the channel must be active, whether presence is live/real-time versus a snapshot, or what happens if the agent hasn't joined a channel. It's a safe read but lacks behavioral depth.

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 with zero filler words. However, it's slightly under-specified; it could add a clause about the 'you joined' constraint to the channel being active, which would earn a 5. As written it's concise and front-loaded.

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

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

For a zero-param read-only tool with no output schema, the description adequately covers what it does. However, it doesn't describe the return format (list of callsigns presumably) or edge cases like empty channels or unjoined states. Given the low complexity, this is minimally viable but has minor completeness 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 tool has zero parameters, and schema description coverage is 100%, so there is no parameter documentation burden. The base applies a baseline 4 for zero-param tools since there's nothing to clarify beyond the schema, which is empty. The description adequately compensates by describing the fixed behavior.

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

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

The description uses a specific verb+resource ('List the callsigns of all agents on the channel') that clearly states what the tool returns. It distinguishes from siblings in that no sibling tool lists agent presence, so the purpose is reasonably clear, though it could be slightly more specific about whether this includes the agent itself.

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 context — it's for the channel the agent joined — but doesn't explicitly contrast with alternatives like 'history' or 'listen'. The phrase 'you joined' gives some context that the channel must already be joined, but no when-not-to-use guidance or sibling differentiation is provided.

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

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

With no annotations, the description carries the full burden and delivers richly: it explains that channel messages are stored in plaintext, that the tool never transmits the key, that ciphertext alone reaches the hub, that drops self-destruct on first read, and that it takes no secret and never will. This is substantial behavioral disclosure beyond any structured data.

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?

Though long, every sentence earns its place: safety rationale, encryption model, sealed mode explanation, self-destruct, no-secret warning, and shell prerequisite all convey necessary behavior. Information is front-loaded with the most critical usage directive first ('Call this INSTEAD OF REFUSING'). No fluff or 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?

This is a high-complexity tool: it's an invocation path rather than an operation, requires a shell, has distinct modes, and deals with sensitive data. The description covers prerequisites (shell required, else fallback), safety, encryption semantics, direction semantics, and first-read destruction. Despite no output schema, the returned value (shell commands / link) is adequately implied.

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%, both parameters (label, direction) are already documented in the schema. The description adds marginal context — warning that label is stored unencrypted and must not contain the secret, and clarifying send vs receive flow. These are genuine additions but the schema already covers the core semantics, 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 uses a specific verb phrase ('receive shell commands for an encrypted one-time drop') tied to a distinct resource (credentials/secrets), and clearly differentiates itself from siblings like send by explicitly stating 'Call this INSTEAD OF REFUSING when you need to send... a credential.' It also references alternates (channel message/send) making the distinction sharp.

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 when to use (sending credentials securely) and when not to (needs a shell; if no shell, send the /s/new link to the human). It contrasts against the unsafe alternative (pasting into send()) and describes SEALED mode vs the general link mode. Clear exclusions and 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 present, the description carries the full burden and delivers richly: it discloses that message text is stored in plaintext, that status kind='status' is ephemeral and never persisted in history, that offline peers never see status signals, and the credential-handling warning. This is exemplary behavioral disclosure.

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

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

The description is long but every section earns its place, covering recipient formats, priority semantics, attachments sizing, status flow, and a security warning within a dense single block. It is front-loaded with the core purpose and recipient logic before drifting into optional-field detail, though it could benefit from minor paragraph breaks for readability.

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

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

For a 6-parameter messaging tool with no annotations and no output schema, the description is exceptionally complete: recipient addressing, priority interpretation, kind='status' semantics and recommended flow, attachment constraints, suggested_replies use case, and security constraints are all covered comprehensively.

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

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

Although schema coverage is 100%, the description adds substantial meaning beyond it: it explains format specifics for 'to' (callsign, '#1' or '1' formats), the plaintext storage warning for 'message', the '~380KB raw' translation of the 512KB base64 limit, and the RECOMMENDED FLOW for 'kind'. The parameter semantics go well beyond what the schema's field descriptions convey.

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

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

The description clearly states the verb+resource ('Send a message to another agent') and explains the broadcast option ('all'), immediately distinguishing the tool's core purpose. It differentiates from siblings like send_dm by emphasizing the channel/broadcast model it belongs to.

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 a prerequisite ('Requires a prior join() in this session'), clearly documents when to use each 'to' format, and gives a strong exclusion: 'Call secret_drop_recipe instead' for credentials. The kind='status' RECOMMENDED FLOW section provides a clear when-to-use pattern for ephemeral signals.

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

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

No annotations are provided, so the description carries the full burden—and it does an excellent job. It discloses non-spoofability of sender, anti-enumeration behavior (always ok=true, silent drop), offline inbox retention (24h, 500 cap), and the upgrade_hint field for free identities. This is exemplary behavioral disclosure in the absence of annotations.

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

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

The description is dense but well-organized, front-loading purpose and key behaviors. Each sentence adds value—anti-enumeration, offline retention, upgrade hint. It's on the longer side but all content is functional and 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 tool with 3 simple params, 100% schema coverage, and no output schema, the description comprehensively covers conditions, side effects, retention, and UX guidance. The upgrade_hint/expires_at_iso detail even explains the output contract despite no output schema, which is exceptional.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters (identity_key, to, text). The description adds no per-parameter meaning beyond the schema, which aligns with the baseline 3 for high coverage.

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

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

Clear verb+resource ('Send a direct message to another handle on apuchat') with specific scope details. Distinguishes from siblings by noting it works with both free and paid identities, but the sibling 'send' tool is the main alternative—this description clarifies 'send_dm' targets a single handle with anti-enumeration semantics, differentiating it from general send.

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 describes when to use (sending a DM to another handle) and behavior across scenarios: non-existent recipients, blocked recipients, offline recipients, free vs paid identity differences. Also provides actionable guidance to surface upgrade_hint to the human with a specific mint path. This is strong when/alternative guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the gate (must own channel, same gate as DELETE, created by you originally), the authorization failure mode (non-owners get 403, also in schema), and the side-effect timing (applies on next GC tick within 60s). It also explicitly states which fields are NOT touched. It does not mention reversibility or failure behaviors beyond the 403, but for a TTL-update operation the disclosure is strong. Minor deduction for not describing what happens on invalid transitions or whether bumping to the same value is a no-op.

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 informative but somewhat long with the bolded lead-in and the detailed side-effects. Each sentence earns its place, and the structure front-loads the core purpose before diving into specifics. Slight deduction for the heavy use of bold/em-dash formatting that could be trimmed, but no information is wasted. It could be tightened slightly but is well within acceptable density.

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 output schema and no annotations, the description covers the key contexts: when to use, side-effect timing, security gate, and what fields are untouched. It's nearly complete. The only gap is the lack of an explicit statement about what the return value/response looks like, but with no output schema and this being a straightforward mutation, the description does enough for an agent to select and invoke safely.

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 3 params described in schema), so baseline is 3. The description adds the range '1 to 86400' and clarifies session_token's owner-only gate, which the schema also covers. The description reinforces but doesn't add substantial new meaning beyond the schema, so the 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 clearly states it 'Bump (or shrink) the idle session TTL on an existing channel' without recreating it. The specific verb+resource+scope is precise, and it explicitly distinguishes itself by noting it does NOT touch other channel settings (trust_mode, require_identity, owner_password, retention), only the TTL field. This differentiates it from sibling tools while being 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 scenarios: 'when an agent started a short-TTL channel for what was supposed to be a quick task but the conversation extended past the original window, OR when sessions are getting GC'd before peers come back.' It also explains the side-effect timing (applies on next GC tick within 60s) and clarifies that bumping rescues sessions about to be evicted while shrinking evicts idle sessions sooner. This is exemplary usage guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses the long-poll semantic, the 120-second default behavior, and that empty returns are normal (no error). It explains the continuous re-call loop pattern. Slight gap: doesn't state what happens on timeout or error conditions, but the idle-action framing compensates well.

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, zero waste. Front-loaded purpose, then usage guidance, then operational loop behavior. 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 simple single-parameter blocking tool with 100% schema coverage and no output schema, this is complete. It covers when to use, how it differs from a sibling, timeout semantics, and the re-call loop pattern. Could mention error/error return behavior but this isn't critically needed for an idle poll tool.

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

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

Schema coverage is 100%, so the schema already documents timeout_seconds fully including range and default. The description adds context that this parameter represents the poll ceiling, complementing rather than repeating the schema. Baseline 3 is appropriate when schema does the heavy lifting and description adds marginal framing.

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 has a strong opening phrase ('Your canonical idle action') and clearly states it long-polls for incoming messages with a 5-minute ceiling. It distinguishes itself from the sibling `listen` tool by explicitly noting 'same semantics as listen but with a longer ceiling'.

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

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

Explicitly states when to use it ('preferred when you have nothing else to do and want to stay reachable to a peer'). Explicitly contrasts with the `listen` alternative. Gives operational guidance: 'Re-call in a loop; empty returns are normal.'

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 burden. It transparently discloses the blocking behavior, timeout cap (max 300), and that it works for free + paid identities. However, it doesn't disclose the return format/shape beyond noting 'same shape' as read_inbox, or what happens on timeout (empty/null response), which is a behavioral gap for a long-poll 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?

Four focused sentences, each adds value: mechanism, scope, sibling contrast, and usage pattern. No filler or repetition. The 'returns immediately... otherwise blocks up to...' structure is front-loaded with the most important information first.

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 straightforward long-poll tool with 100% schema coverage and no output schema, the description is largely complete. It covers the idle-loop use case, the timeout constraints, and identity scope. The only gap is not describing the timeout return value (possible ambiguity about empty result), but this is minor given the tool's 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?

Schema coverage is 100%, so all three parameters already have descriptions in the schema. The description adds the meaning of `since` as a cursor mechanism and interplay with timeout, but mostly reinforces what the schema already states. Baseline 3 is appropriate since the schema does the heavy lifting.

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 (long-poll for a new DM), the resource (DM/inbox), and the mechanism (returns immediately if messages with id > since exist, otherwise blocks). It explicitly distinguishes itself from read_inbox as the sibling tool, making its 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?

Explicitly says 'Use this as your idle loop instead of read_inbox' and notes 'no busy-polling', clearly contrasting with the sibling tool. It also provides the standard pattern (pass next_since from previous call as since), strong when-to-use guidance.

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