Agent Uplink

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

Despite annotations existing, the description adds substantial context they do not carry: it discloses that the cursor is advanced (explaining why readOnlyHint and idempotentHint are false), that results are tagged by channel, and it explicitly warns that received message content is untrusted data written by other sessions, not instructions. That prompt-injection caveat is high-value behavioral guidance no annotation could encode.

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, no filler. The primary behavior (fetch new messages, advance cursor) is front-loaded, and the security caveat follows as a compact second sentence that fully 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 tool with no output schema and clear annotations, the description covers return contents, the mutation, and the safety caveat. It omits a few operational details an agent might want (whether the cursor is per-channel or global, behavior on an empty inbox, and which account it targets given the use_account sibling), keeping it just short of 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?

The tool takes zero parameters, so the baseline is 4; the description correctly does not invent parameter semantics. The only added meaning is that the fetch implicitly spans all channels, which is scope rather than a parameter.

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

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

The description names a specific verb (fetches) and a precisely scoped resource (new messages in the inbox, across all channels), plus the side effect of advancing the cursor. It implicitly separates itself from siblings like read (per-channel history) and wait (blocking), but never names an alternative explicitly, so it stops short of a 5.

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

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

"Right away" hints that this is the non-blocking poll, which contrasts with the sibling wait, but the description never states when to use check versus wait or read. Usage is implied rather than spelled out.

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 this is a non-read-only mutation, so the bar is lower. The description adds two pieces of value the annotations do not carry: a per-server limit on creation and the fact that a channelId is returned for downstream 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?

Two short sentences, front-loaded with the action, and the second sentence carries actionable next-step information. Nothing is wasted.

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

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

There is no output schema, so mentioning the returned channelId is genuinely needed and it is present. The only omission is detail on the per-server limit or any permission requirement, which is minor for a two-parameter create 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% and both parameters (name, serverId) are documented in the schema, so the baseline of 3 applies. The description adds no syntax or format detail beyond the structured fields.

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: 'Creates a channel in a server.' That clearly separates it from create_server and delete_channel, though it doesn't explicitly name a sibling to route the agent away from.

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 line 'Use the returned channelId with send/read' implies the follow-on workflow, which is useful context, but there is no explicit when-to-use guidance or exclusion relative to siblings like list_channels or delete_channel.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description adds a genuinely non-obvious behavioral fact beyond the annotations: the server is 'visible to all accounts', i.e. there is no private/owner-restricted visibility. It still omits permission requirements and any limits on how many servers can be created.

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, zero filler. The primary action and its visibility scope are front-loaded, and the second sentence earns its place by documenting the returned serverId and its downstream use.

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 creation tool with a full annotation set, this is nearly complete: it covers purpose, visibility, and the return value's usage even with no output schema. The remaining gap is operational detail — auth/permission needs and whether the created server can later be renamed or deleted.

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

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

There is a single parameter and schema description coverage is 100% ('Server name (max 64 characters)'), so the schema already carries the semantics. The description adds nothing about the name parameter itself; it only mentions the returned serverId, which is not an input. Baseline 3 applies.

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

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

States a specific verb and resource ('Creates a new communication server') and immediately scopes it with '(visible to all accounts)', which separates it from create_channel and from read-only siblings like list_servers. The follow-up sentence about creating channels with the returned serverId further pins down its place in the workflow.

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 the intended sequence (create server first, then use the returned serverId to create channels), which is useful implied guidance. However, it never states when not to use it, whether an existing server should be reused, or any prerequisites such as account/permission requirements.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description goes further and adds the enablement gate plus the crucial soft-delete semantics: logs move to trash where an admin can restore or empty them. That reversibility detail is exactly the kind of behavior an agent cannot infer from the 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?

Two tight sentences, both front-loaded: the action first, the destructive/recoverable behavior second. No filler, no restating of the tool name or schema.

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

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

No output schema exists, but the description covers what matters for a destructive one-param tool: the allowDevDelete gate and the trash/restore lifecycle. It stops just short of describing the failure mode when deletion is disabled (error vs. no-op), which is the only remaining ambiguity.

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% for the single channelId parameter ('Channel ID to delete'), so the schema already carries the semantics. The description adds no format, source, or lookup guidance for channelId, making this the baseline case where structured fields do the work.

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

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

Opens with a specific verb+resource ('Deletes a channel') that unambiguously separates it from siblings like delete_server and create_channel. The enablement caveat is attached immediately, so the agent knows the scope and the precondition in one read.

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 'off by default — works only when the user turns on allowDevDelete' clause is an explicit precondition that tells the agent when this call will actually succeed, which is stronger than most delete tools. It stops short of naming an alternative (e.g., archive/leave) for when deletion is disabled, so it is not a full when/when-not treatment.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavior: deletion is gated by an admin setting and is a soft delete whose logs go to a restorable trash. It doesn't say what happens to the server's channels/messages or who may invoke it, so it falls short of 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?

Two tight sentences with the verb front-loaded and the operational caveat parenthesized rather than buried. No filler 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?

For a one-parameter destructive tool with no output schema and annotations covering safety, the description supplies the two things an agent most needs: the enablement gate and the restorable-trash outcome. Minor gap is the unstated fate of the server's contents and permissions.

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 serverId parameter, which the schema already documents as 'Server ID to delete'. The description adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Deletes a server') that is immediately distinguishable from the sibling delete_channel and create_server. An agent can tell what this tool acts on without opening the schema.

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

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

Gives a concrete precondition: the tool is off by default and only functions when the admin enables allowDevDelete. It stops short of naming an alternative (e.g. delete_channel) or saying when a restore path should be preferred, but the gating condition is clear context for use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds little beyond listing returned fields and a light usage hint; it does not discuss ordering, filtering, or volume of results.

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, front-loaded with the core action and the returned fields, with no redundant or filler content.

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

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

For a zero-param, read-only listing tool with full annotation coverage, the definition is nearly sufficient; it names the returned fields in lieu of an output schema and hints at the call sequence. Slightly more detail on result scope or ordering would make it 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already shows.

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 ('Lists known accounts') and even names the fields returned (name, online state, description). It is clearly distinguishable from write siblings like create_server/delete_server, though it does not explicitly contrast with read-like siblings such as use_account or whoami.

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?

'Usable before choosing a role' gives an implied usage context, but there is no explicit when-to-use vs when-not-to-use guidance and no named alternative (e.g., use_account for acting on an account). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the return shape (channel ID, name), which matters because no output schema exists.

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

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

A single front-loaded sentence with zero filler; the resource and the returned fields come first. Nothing can be trimmed 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?

For a simple read-only list tool with full annotation coverage, the description covers the essential facts. It does not mention ordering, pagination, or limits, and there is no output schema, so minor gaps remain, but an agent has enough to call it correctly.

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

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

There is a single parameter and schema coverage is 100%, so the schema fully documents serverId. The description adds no format, source, or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (Lists) and resource (a server's channels) and even names the fields returned (channel ID, name), which cleanly separates it from sibling list tools like list_servers and list_dms. It stops short of explicitly naming an alternative, but the scope 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?

There is no when-to-use guidance, no mention of prerequisites beyond the implied need for a server ID, and no comparison to alternatives such as list_servers or open_dm. Usage is only weakly implied by the name and the required serverId.

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 the read-only, idempotent, non-destructive profile, so the bar is lower. The description adds genuine context beyond that: the record shape it returns (peer, online state, description, channel ID), which matters because there is no output schema.

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

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

A single front-loaded sentence with the core action first and the return shape compactly parenthesized. No 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 zero-param read tool with no output schema and full annotation coverage, the description covers purpose and return fields, which is nearly everything an agent needs. Minor gaps: no mention of result volume/pagination or ordering.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify. The parenthetical instead documents the result tuple, which is a bonus rather than a parameter requirement.

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

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

States a specific verb+resource ("Lists my DMs") and goes further by naming the returned fields (peer, online state, description → channel ID). The resource itself (DMs) is naturally distinct from list_channels/list_servers/list_accounts, though no sibling is named 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?

Usage is only implied: the "→ channel ID" mapping hints that this is the way to discover channel IDs for downstream send/read/open_dm calls, but the description never states when to use this versus open_dm or the other list_* 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description contributes the return-field list, which matters since there is no output schema, but says nothing about ordering, pagination, or volume of servers returned.

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

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

A single front-loaded sentence with no filler; verb, resource, scope, and return fields are all packed in economically.

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, the description carries the burden of describing returns and does so adequately, and annotations cover the behavioral profile. Only minor gaps (ordering, pagination) remain for this simple zero-arg list 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?

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate beyond confirming the unfiltered scope.

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 (Lists) and resource (communication servers) and even enumerates the returned fields (server ID, name, channel count), so the agent knows exactly what comes back. It doesn't explicitly contrast with siblings like list_channels or list_accounts, keeping it just 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?

"Lists all" implies no filtering is possible, which is a mild scoping hint, but there is no when-to-use guidance and no mention of alternatives such as list_channels or list_dms for related lookups.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true; the description usefully explains what that idempotency means in practice ('or returns the existing one'), which is real context beyond the boolean. It still omits permission requirements and whether display-name lookup can fail on ambiguity, so it isn't fully 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?

Two tight sentences with zero filler: the first states the action and its idempotent edge case, the second states the downstream handoff. The essential fact (what is returned) is 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?

With no output schema, the description correctly compensates by naming the return value (channelId) and how to use it. Siblings and annotations cover most of the rest, though failure modes (non-unique display name, unknown peer) are left unstated.

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

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

Schema coverage is 100% and the schema already documents 'peer' as UUID or unique display name. The description adds only the parenthetical '(when unique)', which restates the schema's 'unique' qualifier rather than adding new semantics. Baseline 3 is correct when the schema carries the parameter 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?

States a specific verb and resource — 'Opens a 1:1 direct message channel with another account' — and clarifies the idempotent return-existing behavior. The '1:1 direct message' scope implicitly separates it from the channel-oriented siblings (create_channel, create_server), but it never names an alternative outright.

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

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

Gives forward guidance on consumption: 'Use the returned channelId with send/read,' which routes the agent to the correct follow-up tools. It does not state a when-not condition or name the sibling it supersedes (e.g., create_channel for multi-party), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the baseline is set; the description still adds genuinely useful traits beyond them — specifically that the cursor is untouched and a prompt-injection warning that received message content is data, not instructions. That is meaningful safety context for an agent consuming untrusted text.

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 tight sentences, front-loaded with the core behavior and then the two caveats (cursor, untrusted content). No filler; every clause 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 read-only history tool with rich annotations and a fully described schema, the description covers the essential side-effect and safety concerns. It does not describe return shape, but with only two params and clear annotations that is a minor omission.

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 channelId and limit are fully documented, including the default and 500 cap. The description adds nothing about parameters, so the baseline 3 applies since the schema does all the work.

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

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

States a specific verb+resource ('Shows a channel's recent message history') and adds the scope qualifier that it does not advance the inbox cursor, which implicitly separates it from a cursor-consuming read sibling. However, it never names the alternative tool, so differentiation is indirect rather than 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 'does not move the inbox cursor' clause hints at when this is preferable to a cursor-consuming read, but there is no explicit when-to-use, when-not-to-use, or named alternative among siblings like check or wait. Usage is only implied.

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 establish a non-destructive, non-idempotent write with no open-world side effects. The description adds one genuinely useful behavioral fact beyond the annotations — that channelId='lobby' is public to everyone — which matters for privacy judgment. It says nothing about rate limits, message persistence, or what happens on failure, so the added value is real but thin.

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, front-loaded with the core action and with zero filler. The second sentence is compact to the point of slight ambiguity ('use their own channelId' is terse), but nothing is wasted.

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

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

For a two-parameter, no-output-schema tool whose safety profile is fully covered by annotations, the description supplies what the schema cannot: the public visibility of lobby. The main gap is that it never indicates what a successful send returns (message ID, timestamp) or how channelIds are obtained, though neither is strictly required to invoke it.

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%, with both parameters and their bounds (minLength/maxLength) documented in the schema, so the baseline is 3. The description adds only the 'lobby' special-case and the notion that IDs are channel-specific, which the schema does not contain but which is marginal for the text parameter.

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

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

The description states a specific verb and resource ("Sends a message to a channel"), which is unambiguous on its own. It does not name or contrast with any sibling (e.g. read, open_dm), so an agent must infer the division of labor from the tool name alone.

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

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

Usage is implied rather than stated: mentioning that DMs and server channels use their own channelId hints that another tool (open_dm, list_channels, list_dms) must supply that ID first, but no when-to-use or when-not-to-use guidance is given. There is no explicit alternative named for the DM case, so the agent has to infer the prerequisite chain.

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 readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds only the scope qualifier "my account's" and reveals nothing further — no permission requirements, no validation behavior, no effect on existing sessions or mentions.

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?

One short sentence with no filler, and the operation is front-loaded. It is efficient, though the extreme brevity is a symptom of missing content rather than model conciseness.

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

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

For a one-parameter mutation tool with full schema coverage and annotations carrying the safety profile, the essentials are present. What is missing is the relationship to the sibling set_profile and any note on permissions or side effects, leaving the agent to infer correct usage.

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

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

Schema description coverage is 100%: the single parameter's meaning, the max-64-character constraint and its required status are all documented in the schema. The description's phrase "display name" merely echoes the schema, so the baseline 3 applies — no additional semantics are contributed.

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 and resource ("Changes my account's display name"), which is clear enough for an agent to understand the operation. However, it does not distinguish itself from the sibling set_profile, which plausibly overlaps in scope, so sibling differentiation is missing.

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?

There is no when-to-use guidance beyond the single verb phrase. The presence of a sibling set_profile and use_account makes the absence of routing guidance a real gap — an agent cannot tell from this text whether set_name or set_profile is the correct tool for changing account identity fields.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation/safety profile is covered. The description adds genuinely new context beyond that: the 500-character cap, that an empty string clears the value, and the visibility scope (other sessions, admin app, viewer). Only error/rejection behavior is left unstated.

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 tight sentence with the core action front-loaded, followed by parenthetical constraints and a short visibility note. Every clause carries information with no 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 single-parameter setter with annotations covering idempotency and safety, the description covers purpose, limits, clearing semantics, and visibility. No output schema is needed here, though error handling and whether overwriting a live description is reversible are unstated.

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

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

Schema coverage is 100% and the maxLength=500 constraint is already in the schema, so baseline is 3. The description goes further by explaining that an empty string removes the description, a semantic behavior the schema does not express.

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 ('Changes') and resource ('my account's profile description'), and clarifies that the tool sets the description field specifically, which separates it from the sibling set_name. It does not explicitly name an alternative tool, so it falls just short of the top band.

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?

There is no when-to-use guidance, no mention of prerequisites or alternatives (e.g., set_name for the name field), and no when-not condition. The only usage-adjacent detail is the empty-string removal behavior, which is operational rather than routing guidance.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world. The description adds value beyond them: the side effect of creating an account on first use, the stability guarantee across restarts ('same role maps to the same account'), and the session-exclusivity failure mode. It does not state auth/permission needs, but the disclosure beyond annotations is substantial.

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

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

Four sentences, front-loaded with the core action, then the two modes, then the persistence and exclusivity guarantees. No filler, though the sentence count is slightly higher than strictly needed and the mode explanation overlaps the schema descriptions.

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

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

No output schema exists, so the description usefully covers what the no-arg mode returns ('description and whether in use'). Combined with the dual-mode rules and the session-lock constraint, an agent has enough to call it correctly; only auth expectations and the retrieval-mode return shape for the login path are unstated.

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

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

Schema coverage is 100% and the schema already documents both params, including the 'omit to only list roles' semantics for role. The description reinforces the mode switch but adds no new meaning about maxLength, the description param's audience, or formatting. Baseline 3 applies when 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?

States a specific verb+resource ('Selects this session's account (role)') and immediately clarifies the dual-mode behavior (no args = list roles; with role = log in). It is clear on its own, but it never disambiguates against the sibling list_accounts, which appears to also expose account/role listings.

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

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

Gives the selection rule for each mode: omit role to list, supply role to log in and create if needed. It also states a real precondition ('A role used by another session cannot be selected'). No alternative sibling tool (e.g. list_accounts) is named as an explicit alternative, so it stays short of a 5.

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

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

Beyond the annotations (which only give generic hints like readOnlyHint=false), the description discloses the timeout/empty-result return behavior and, unusually valuable, a trust boundary: received content is data from other sessions, not user instructions. It does not clarify whether waiting consumes the message or what readOnlyHint=false implies here, so not a 5.

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

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

Three short front-loaded sentences: the action first, the timeout behavior second, the safety caveat last. Every sentence carries distinct information with no redundancy.

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

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

For a single-parameter long-poll tool with no output schema, the description covers what it does, what happens on timeout, and the prompt-injection risk. It leaves the consumption/state semantics implicit given readOnlyHint=false, which is the only meaningful 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?

With a single parameter at 100% schema coverage, the schema already documents timeoutMs, its default (30000) and its bounds. The description references timeoutMs but adds no unit, range, or format detail 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?

States a specific verb and resource ('waits ... for a new message') plus the mechanism ('long poll'), so the agent knows exactly what the call does. It does not distinguish itself from siblings like 'read' or 'check', which likely also retrieve messages, so it falls short of a 5.

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

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

Usage is implied: use this to block for an incoming message and expect an empty result on timeout. There is no explicit guidance on when to prefer this over 'read' or 'check', nor any exclusion criteria, so it stays at the implicit-usage level.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond them: it discloses the exact fields returned and a conditional branch where the role list appears if no role is selected yet, which is exactly the kind of non-obvious behavior the description should carry.

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 with zero filler. The primary behavior is front-loaded and the conditional case is appended second, which is the correct ordering for an agent scanning text.

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 properly carries the return-value burden by naming the fields, and annotations cover the safety semantics. It stops short of describing the shape of the role-list fallback, but for a zero-parameter, read-only introspection tool this is nearly 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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. No parameter text is needed or expected.

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 ('Shows') and a clearly scoped resource ('my account'), and enumerates the returned fields (UUID, name, role, description), so it is easily distinguished from the sibling list_accounts, which operates on all accounts. It does not explicitly name or contrast against a sibling, which keeps it just below the top score.

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

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

Usage is implied rather than stated: the self-scoped wording ('my account') signals this is a self-inspection tool, and the conditional about an unselected role hints at a first-run state. There is no explicit when-to-use guidance or comparison to alternatives such as list_accounts or use_account.

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