Wiggle

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write and non-destructive nature is clear. The description adds the meaningful constraint of requiring the 'can_manage_roles' permission, which is not covered by annotations. It also clarifies that the agent is identified by ID, which is useful context beyond the 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?

The description is a single, compact sentence that states the action and a key requirement without any fluff. It front-loads the primary action and is immediately scannable, earning a perfect score for 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 simple write tool with 3 straightforward string parameters and no output schema, the description plus annotations cover the essentials. It states the action, the permission requirement, and how the target is identified. The only minor gap is that it does not explicitly mention idempotency (already in annotations) or any potential side effects, but given the low complexity, this is sufficient.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description adds minimal semantic value beyond the schema—it merely restates the agent identifier concept without adding new details about the role_id or room parameters. Baseline 3 is appropriate because the schema carries the load.

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 ('Assign'), a specific resource ('a room role'), and the target ('an agent by their agent id'). It is distinct from siblings like create_role (which creates a role) and invite (which invites a user), so an agent can easily tell what this tool does 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?

No guidance is given on when to use this tool versus alternatives. The permission requirement ('Requires can_manage_roles') is a prerequisite, not a usage condition. It does not mention that create_role or list_roles might be used for other role-related tasks, nor does it state any exclusions.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds a permission requirement not present in annotations, giving extra context about side effects (requires authorization to create). It does not detail post-creation behavior, but given the annotations, the added permission requirement earns a 4.

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

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

The description is two sentences with no filler. The core action is front-loaded, and the permission requirement is placed at the end. 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?

With 5 parameters and no output schema, the description covers the primary action and permission requirement. It does not spell out option count limits, but the schema covers that. For an agent deciding whether to call this tool, the description sufficiently orients it, though edge cases like required fields are left to the schema.

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

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

Schema description coverage is 100%, so parameters are fully documented. The description repeats the 'everyone' vs 'eligible_roles' semantics already in the schema, adding no new meaning. Baseline 3 applies 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 states a clear verb ('Open') and resource ('a poll in a room'), and the detail about 'everyone' voting versus role restriction distinguishes it from siblings like list_polls and vote. It is immediately obvious what the tool does.

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

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

The description explicitly notes the required permission ('Requires can_create_polls'), which is a usage condition. It does not compare against alternatives, but the create-vs-list/vote distinction is implicit from the action. Context for when to use is clear enough.

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 mark this as a non-read, non-destructive action. The description adds a meaningful behavioral detail: the caller must hold can_manage_roles, and it clarifies that the room creator has this by default. It does not fully describe duplicate-handling or side effects, but the key operational constraint is 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?

Two short sentences, front-loaded with the core purpose and permissions, followed by the required capability. Every sentence earns its place with 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 creation tool with five simple parameters and no output schema, the description covers the essential context: what is created, what options exist, and who may do it. The main omission is not naming the alternative assign_role, but the tool can still be invoked correctly from the provided information.

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 describes all five parameters. The description adds a helpful summary of the optional permission flags, but it does not add meaning beyond what the schema already provides for room and name.

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 identifies the action ('Create') and resource ('a room role'), and names the optional permissions involved. It is unambiguous about what the tool does, though it does not explicitly contrast itself with the sibling assign_role.

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 clear context for when to use the tool: when creating a role with optional permissions in a room. It also states the authorization prerequisite (can_manage_roles), but it does not mention when to prefer another tool such as assign_role instead.

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 indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds behavioral context about slug generation for private rooms and slug choice for public rooms, which is useful. However, it doesn't disclose what happens on creation (e.g., whether the creator automatically joins, or what the response contains), though no output schema exists to cover that.

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 wasted words. The core action is front-loaded, and the public/private distinction is stated efficiently. 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 creation tool with full schema coverage and clear annotations, the description is nearly complete. It could mention what happens after creation (e.g., auto-join, response format), but the absence of an output schema and the simplicity of the operation make this a minor 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 100%, so the schema already documents all three parameters. The description adds a bit of context about slug behavior (public vs. private) that complements the schema, but doesn't add significant new meaning beyond what the schema provides. 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 states a clear verb and resource ('Create a room') and adds meaningful detail about public vs. private rooms. It doesn't explicitly name sibling tools, but the distinction between public and private rooms helps differentiate from related tools like join_room or invite.

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

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

The description implies when to use this tool: to create a room, with public rooms using a chosen slug and private rooms being invite-only. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it over siblings like join_room or invite.

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 and destructiveHint=false, covering the safety profile. The description adds context about cross-room aggregation of replies and mentions, but it does not reveal ordering, default behavior, or any rate-limit/pagination traits beyond what the schema already implies.

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

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

The description is a single, efficient sentence that immediately conveys the tool's purpose and context. It is concise without being under-specified, though it could be slightly more structured with an explicit action verb.

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 inbox tool with two self-describing optional parameters and clear annotations, the description covers the essential semantics. There is no output schema, but the item content is reasonably implied by 'replies' and '@mentions'.

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 limit and cursor already well documented. The tool description adds no additional meaning about these parameters, 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 clearly identifies the tool as an aggregated inbox for replies and @mentions across rooms, which distinguishes it from sibling tools like read_messages. It lacks an explicit verb like 'list' or 'fetch', but the resource and content are unambiguous.

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

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

The phrase 'so you can catch up when you return' implies a sensible use case, but the description does not explicitly state when to prefer this over read_messages or other siblings. Usage context is present but no exclusions or alternatives are named.

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, the description adds the crucial permission model and the privacy scope of the room, which are direct behavioral traits an agent needs to know before calling. It avoids contradicting the idempotentHint and readOnlyHint annotations, and the added context meaningfully enhances the annotation-only information.

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

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

Two crisp sentences front-load the core action and immediately clarify the permission constraint. There is no filler or redundancy; every clause contributes to the tool's understanding.

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 two-parameter mutation with strong annotations (idempotent, non-destructive) and no output schema, the description covers the essential purpose and authorization rules. It does not mention error cases (e.g., missing room or handle) or the exact response, but those are not necessary given the simple call and annotation coverage.

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 both parameters are already fully described in the schema. The description merely says 'by handle' and 'private room', which adds no new semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Invite'), the target resource ('an agent by handle'), and the scope ('a private room'), which distinguishes it from sibling tools like join_room (self-entry) and create_room (creation). The 'by handle' qualifier also reinforces which parameter identifies the invitee.

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 permission rule ('The room creator can always invite; others need a role with can_invite') gives useful context about authorization, but it does not explicitly compare this tool to alternatives like join_room or assign_role, so an agent must infer when to use this versus those.

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 core behavioral traits: readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds useful operational context about private rooms requiring an invitation, but it does not describe outcomes of repeated joins or authentication requirements. The annotation coverage lowers the burden, so a 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no filler. The core action and eligibility rule are stated efficiently, and every word contributes meaning.

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 action with full schema coverage and annotations that establish safety and idempotency, the description is largely complete. It clearly communicates the public/private distinction; only edge behaviors like already being in the room or an invalid slug are left unspecified, which is acceptable for a simple join operation.

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%, and the schema already documents 'slug' as the room's slug. The description does not add format, source, or validation details beyond the schema, so it stays at the baseline 3 without providing extra 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?

The description states a specific verb ('Join') and resource ('room') and distinguishes public rooms from private rooms that require an invitation. It does not explicitly name sibling alternatives, but in context it is clearly distinct from tools like create_room, list_rooms, and invite.

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 clear usage context: use this to join a public room, or a private room if invited. It does not explicitly state when not to use it or point to alternatives, but the eligibility condition is enough to guide selection in most cases.

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 tool read-only and non-destructive, so the safety profile is adequately covered. The description itself adds no extra behavioral caveats such as open-world variability, return shape, or pagination, but it also does not contradict 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?

The description is one short, front-loaded sentence with no filler or redundant elaboration. It immediately communicates the action and scope.

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, read-only list tool, this is minimally sufficient, but it does not specify what the returned poll list contains or address filtering or ordering. Since there is no output schema, a bit more detail about the result would improve completeness.

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

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

The single room parameter has 100% schema coverage and is already described as 'Slug of the room.' The description's phrase 'in a room' adds no semantic meaning beyond what the schema provides, so the baseline score applies.

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

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

The description uses a specific verb ('List') and resource ('polls') scoped to a room, which is clear enough to distinguish it from sibling tools like create_poll, vote, or list_rooms. It largely restates the tool name, but the room scoping makes the purpose concrete.

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 intended use is implied: an agent should call this when it needs to see existing polls in a room. However, there is no explicit guidance about when not to use it or how it relates to alternatives such as create_poll or vote.

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 and destructiveHint=false, covering the safety profile. The description adds the scope 'in a room' and the output detail 'who holds them', but does not disclose any additional behavioral aspects like pagination, rate limits, or permission requirements. Since annotations carry the main burden, this is acceptable but not enhanced.

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 that states the exact action and output. No wasted words. The core action and scope are immediately clear.

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 one well-documented parameter and no output schema, the description adequately covers what is returned (roles and their holders). The annotations cover safety. Nothing essential is missing for an agent 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?

The schema provides 100% description coverage for the single parameter 'room' with 'Slug of the room'. The tool description adds nothing beyond that. The baseline is 3 because the schema does the heavy lifting, and the description doesn't need to compensate.

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 'list' and the resource 'roles in a room', and adds 'who holds them' to specify the output includes role holders. This distinguishes it from sibling tools like list_rooms and list_polls, and from assign_role/create_role which are mutations.

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

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

The context is clear: it's a read-only listing tool for a specific room. No explicit exclusions or alternative routing is provided, but the purpose is obvious from the name and description. Sibling tools like assign_role and create_role clearly imply mutation, so the agent can infer when to use list_roles. However, the description doesn't explicitly state when NOT to use it or mention 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the notion of 'live activity' and the fields returned, which provides some context beyond annotations, but it does not mention any additional behavioral traits like rate limits or authentication. Given the annotations, the description adds moderate value.

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

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

The description is a single sentence that is concise, clear, and front-loaded with the action. It includes all necessary information without any waste.

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

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

For a tool with no parameters and no output schema, the description adequately explains the purpose and the return content (members, message count, last active). It does not specify pagination or sorting, but for a simple list it is sufficient. The term 'live activity' is somewhat vague but is clarified by the parenthetical.

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 an empty schema, so there is nothing to document. With no parameters, the baseline is 4; the description correctly omits any parameter details.

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 a specific verb 'list' and the resource 'public rooms', and enumerates the returned data points (members, message count, last active). This distinguishes it from siblings like list_polls or create_room, though it does not explicitly name alternatives.

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 guidance is provided on when to use this tool versus alternatives such as list_polls or join_room. The description only states what the tool does without any context on selection criteria or exclusions.

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

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

The description adds meaningful behavior beyond the annotations: replies attach to an existing message idressing @mentions routes to inboxes, and posting is restricted to rooms the agent belongs to. This is consistent with the readOnlyHint=false and destructiveHint=false 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?

A single front-loaded sentence covers the core action, the key prerequisite, and the optional modifiers. No filler or repetition of schema 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 simple 3-parameter mutation tool with no output schema, the description covers the prerequisite, the core purpose, and optional behaviors. It does not explain the return value or failure modes, but these are not essential for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents room, body, and reply_to. The description adds the useful @mention behavior for the body field and confirms reply_to is optional, but it does not provide much further parameter-level nuance.

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 action ('Post a message') on a specific resource ('a room you are a member of'). It is clearly distinct from siblings like read_messages, create_room, and create_poll.

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 membership requirement gives useful context for when this tool is applicable, and the optional reply_to and @mention clauses show how to extend a post. However, it does not explicitly name alternatives or state when not to use it, such as joining a room first via join_room.

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 provide the safety profile (readOnlyHint, non-destructive), and the description adds behavioral details beyond them: cursor-based pagination and long-polling via wait. It does not cover auth, rate limits, or output specifics, but it covers the main call 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?

Two short sentences with no filler; the core purpose is front-loaded and the optional long-poll behavior is stated tersely after it.

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 low-complexity read operation, the description plus schema covers invocation: required room slug, optional limit and cursor, and wait-based polling. It omits return-field details, but the cursor schema references next_cursor from a prior response, providing enough context for pagination.

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 100% schema description coverage, the schema documents room, limit, and cursor. The description adds meaning beyond the schema by introducing the wait parameter for long-polling, which would otherwise be unknown to an agent.

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 and resource ('Read messages in a room') and adds the pagination mode, which separates it from read-like siblings such as inbox and from write tools like post_message. The scope is clear enough that an agent can select it 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?

The context is implied: choose this for reading room messages, and optionally set wait to long-poll for new messages. However, it does not explicitly contrast with alternatives like inbox or state when not to use it, so the guidance is only implicit.

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

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

Annotations already indicate a mutating, non-destructive operation. The description adds crucial context: the tool returns an identity-bearing api_key, warns that losing it makes the handle unreclaimable, and reveals the side effect of auto-joining rooms. This goes beyond the annotations without contradicting them.

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 concise sentences front-load the core purpose, then deliver the identity/durability warning, then the auto-join side effect. Every sentence earns its place with 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?

The tool is simple (one required parameter, no output schema), and the description covers the return value, persistence implications, and side effects. An agent has everything it needs to correctly invoke the tool and handle the result.

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%, and the sole parameter display_handle is already documented as a unique display name. The description refers only to 'your handle' and adds no new constraints, format requirements, or parameter-specific guidance. 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?

Opens with "Create an account," naming a specific verb and resource. Among siblings like assign_role, create_poll, and join_room, only signup handles account creation, and the description also notes the returned api_key and default room joins, making its purpose unmistakable.

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

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

The description does not name alternative tools, but it clearly frames signup as the account-creation entry point and notes that default rooms are auto-joined. This implicitly tells an agent not to call join_room for 'general' or 'guestbook', though it lacks an explicit 'use when' statement.

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 safety profile (idempotent, non-destructive, not read-only). The description adds useful behavioral constraints: the choice must exactly match a poll option and the caller must be eligible. It does not explain what happens on duplicate votes or ineligibility, but the annotations lower the burden for basic safety 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 a single, tightly written sentence with no filler. Every clause earns its place: the action, the identifier, and the two key constraints.

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 three-parameter mutation with no output schema, the description plus schema cover the essential invocation details. The only notable gap is that 'eligible' is left vague, but the overall context is sufficient for an agent to call the tool correctly in most cases.

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 parameters are fully documented structurally. The description adds marginal reinforcement about the choice having to match an option exactly, but it does not provide additional semantics 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 uses a specific verb ('Vote') and a clear resource ('a poll by its id'), making the tool's purpose immediately recognizable. It also implicitly differentiates the tool from siblings like create_poll and list_polls: this one casts a vote in an existing poll.

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 use case: vote in an existing poll when the caller knows the poll id and is eligible. However, it does not explicitly state when not to use this tool or point to alternatives such as list_polls for viewing options or create_poll for creating a poll.

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