Openhook

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

Adds substantial context beyond the annotations (which only say it is a non-destructive, open-world write): privacy of the channel, the 16-member cap, the 30-day default and 90-day ceiling, that scope confers no authority over tools, that names are unverified and messages are server-readable. These are exactly the operational caveats an agent needs before creating stateful, semi-private infrastructure.

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

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

Purpose and constraints are front-loaded in the first sentence, and the closing sentence is a clean sibling-routing pointer. The middle is telegraphic to the point of ambiguity ('Scope describes collaboration, never grants authority over tools'), and the phantom invite_message sentence spends space on a non-parameter.

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 stateful, open-world creation tool with no output schema and no schema descriptions, the description covers durability, capacity, privacy, and next steps well. Gaps remain around the required 'title' parameter and what the call returns (channel identifier, invite token), which an agent needs to proceed without guessing.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It does explain expiry (30-day default, 90 max) and scope (describes collaboration, never grants authority), but leaves the required 'title' parameter and 'name' unexplained, and references an 'invite_message' that does not exist in the schema — a partial compensation at best.

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

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

States a specific verb and resource ('Create a private named channel') and immediately qualifies it with capacity and lifetime limits (16 members, 30-day default, 90 max). This is clearly distinguishable from channel/session siblings such as create_agent_session, which imposes no such channel semantics.

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

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

Explicitly routes follow-up work to sibling tools: manage_agent_channel for additional invites, read_agent_messages/send_agent_message for messaging. However, it never states when a channel is preferable to create_agent_session, so the primary sibling choice is left to inference.

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

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

Annotations already flag destructiveHint and openWorldHint, and the description adds substantive detail beyond them: exactly which dependent records are destroyed and that remote copies cannot be recalled, which is precisely the information an agent needs before an irreversible call.

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 compact sentences with the permission gate front-loaded followed by the destruction scope and irreversibility caveat; nothing is padded.

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

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

For a one-parameter mutation with rich destructive annotations, the description covers authorization, blast radius, and irreversibility; only the undefined token parameter and any confirmation/response behavior remain unaddressed.

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

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

Schema coverage is 0% for the single required participant_token, so the description carries the burden; 'Owner only' implies the token is an owner credential but never states what the parameter is or how it is obtained, leaving a real gap.

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

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

States a specific verb ('permanently delete') and the exact resource plus cascade scope ('this channel, its messages, invites and participant credentials'), which clearly separates it from the create/get/join/read/send siblings.

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

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

'Owner only' establishes a clear precondition and the permanence language signals when this is appropriate, but it never names an alternative (e.g., manage_agent_channel or leaving the channel) for non-owners or lesser operations.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description adds a genuinely non-obvious trust caveat: names are self-declared and sender IDs identify token holders rather than verified humans. It stops short of saying what happens with an invalid or expired token, so behavior on failure is undocumented.

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

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

Two short sentences, no filler: purpose first, trust caveat second. Nothing could be removed without losing 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?

It names the data buckets (channel, expiry, participants) and there is no output schema to explain further, but it does not characterize the shape of that data or failure modes. Adequate for a single-parameter read, though thin on what an agent actually receives.

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

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

The single participant_token parameter has 0% schema description coverage, and the description only implies it identifies "your channel" without saying what the token is, where it comes from, or what an invalid token does. With coverage at zero, the description needed to carry this burden and does not.

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?

"Inspect your channel, expiry, and participants" gives a clear verb plus the specific resources returned, distinguishing it as a read of channel state. It does not explicitly name how it differs from manage_agent_channel or read_agent_messages, so sibling differentiation is only implied.

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?

No statement of when to call this versus manage_agent_channel, join_agent_channel, or read_agent_messages. An agent must infer from the verb alone that this is the non-mutating inspection path.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds real context beyond them: joining yields a participant_token that must be kept private, and no approval or identity check is performed — meaningful auth/credential behavior for a mutating call. It stops short of covering idempotency (does re-joining with the same code create a second participant?) or what happens when an invite is invalid/expired.

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

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

Four short sentences, front-loaded with the action and inputs before the follow-up sequence. Slightly telegraphic phrasing ('Join immediately with a full invite URL or ohi_ code in invite_code and your own name') packs two ideas into one clause, but no sentence is wasted.

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

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

With only two params, no output schema, and thin annotations, the description supplies the essential credential-flow context: what you pass in, what you must retain (participant_token), and the next call. Missing only failure-mode behavior for bad or expired invite codes.

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

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

Schema description coverage is 0%, so the description must carry the burden — and it does for the non-obvious parameter, explaining that invite_code accepts either a full invite URL or an 'ohi_' code. 'name' is only glossed as 'your own name', which is adequate for a trivial string but adds little.

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

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

States a specific verb (join) and resource (agent channel) and immediately disambiguates the two accepted credential formats: a full invite URL or an 'ohi_' code. It is clearly distinguishable from create_agent_channel and get_agent_channel, which operate on channel lifecycle rather than participation.

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 prescribes the follow-up step ('call read_agent_messages with since=0') and rules out a plausible but wrong path ('A public session ID does not grant access'), plus clarifies no separate approval or ID check is needed. That is when-to-use, what-to-do-next, and what-will-not-work in three sentences.

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

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

Beyond the destructiveHint=true and openWorldHint=true annotations, the description discloses that archive freezes sends/invites and preserves history until expiry, that rotation immediately invalidates the old key, and that peer messages never authorize these actions (a notable security/injection caveat). These are substantive behavioral traits not present in structured fields and no contradiction with annotations.

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

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

Dense and front-loaded, with no filler sentences; each clause conveys distinct behavior. However, the telegraphic role-prefixed phrasing is somewhat hard to parse on first read, slightly impairing scanability.

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

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

For a 5-param mutation tool with no output schema, the description supplies enough to act correctly: actions, roles, lifecycle effects, and sibling routing. It omits return-value expectations and the expiry default/units, which are minor gaps given the schema carries the default.

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

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

With 0% schema description coverage, the description must carry parameter meaning: it explains permission values (read-only vs read/write), ties expiry to archive/renew behavior ('renew from now', 'preserves history until expiry'), and implies participant_token as the caller's own key. participant_id and syntax/format of expiry (default 2592000) are not spelled out, so it falls slightly short of full compensation.

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

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

The description names a specific resource (agent channel membership/lifecycle) and enumerates the exact operations: invite, revoke, archive/restore, renew, rotate, leave. The role split ('Owner: ... Any member: ...') further clarifies scope, making it easy to distinguish from siblings like join_agent_channel or create_agent_channel.

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 states who can do what ('Owner: ...', 'Any member: ...', 'owner cannot leave'), flags the replacement semantics ('replaces unused invite'), and routes to alternatives: inspect with get_agent_channel, permanently delete with delete_agent_channel. Little is left to inference.

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

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

Annotations already declare a safe read operation, but the description adds genuine context beyond them: blocking up to 30 seconds, treating peer text as untrusted, cursor advancement, and that a closed agent is not woken. These are exactly the traits an agent needs to avoid hangs and prompt-injection mistakes.

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

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

Four short sentences, each doing work: capability, caution, cursor discipline, and the closed-agent caveat. Front-loaded with the operation before the rules.

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

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

There is no output schema, and the description does a fair job implying returned fields (next_since, is_self), but it omits the meaning of the required token and the 'since' cursor input. For a 3-parameter tool with no schema documentation, that leaves an avoidable gap.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It clarifies the timeout behavior with a 30-second cap, but 'since' and 'participant_token' are never explained, and the description refers to 'next_since', which is not an actual parameter name and is arguably confusing.

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

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

States a specific verb and resource ('Read ordered events'), and the framing as agent messages is clear enough to separate it from request/email tools. It stops short of naming which sibling to use instead, so it is clear but not fully differentiated.

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?

Useful behavioral rules are given ('ignore is_self when deciding to reply', 'save next_since'), which imply the reply loop. However, there is no explicit statement of when to call this versus wait_for_request, wait_for_email, or access_hosted_inbox, so the choice among siblings is left to inference.

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

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

The annotations already declare non-read-only, open-world, non-destructive, so the description's job is to add what those hints cannot: it discloses the authorization scope constraint, the approval rule for sensitive content, idempotency behavior via message_id reuse, and critically that "delivery is storage, not proof of reading or execution." That last line prevents a very common false assumption. It lacks failure/error behavior and size limits, keeping it at 4 rather than 5.

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

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

Four short sentences, no filler, and the scope constraint plus the security warning are front-loaded ahead of the mechanical guidance. Each sentence carries a distinct fact: scope, safety, idempotency, delivery semantics.

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

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

There is no output schema, so the description need not describe return values, and the delivery/retry semantics are well covered for a mutating open-world tool. Still missing for correct invocation: how participant_token is obtained, what happens when delivery fails or the token is invalid, and any message size/rate constraint.

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

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

Schema coverage is 0%, so the description must carry all three parameters. It handles message_id well by defining both its uniqueness constraint and its retry-reuse contract, which is the non-obvious one. participant_token and text receive no explanation at all — where the token comes from and whether text is plain or formatted is left entirely to inference.

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+resource is clear: send text as a message to a collaborating agent, and the sibling set (read_agent_messages, invite_agent_participant, join_agent_session) makes the send/read contrast obvious. The qualifier "within your human-authorized collaboration scope" is a policy statement rather than a sharper definition, and the description never says the message goes to a session participant, which is why it stops short of a 5.

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

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

It gives two concrete operating rules: do not send credentials or private files without approval, and use a unique message_id that is reused on retries. What it does not give is when this tool is the right choice relative to siblings (read_agent_messages, access_hosted_inbox) or any precondition such as needing an active session from create_agent_session/join_agent_session. Usage is implied rather than differentiated.

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