VoteShip

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

The annotations (readOnlyHint false, idempotentHint false, destructiveHint false) already indicate this is a write operation that is not idempotent or destructive. The description adds 'public context' and 'follow-up' but does not provide additional behavior details such as return values, side effects, or error scenarios. It adds minimal nuance beyond 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 concise but contains some redundancy. The first sentence ('Use this when...') and the second sentence ('Add a comment...') largely repeat the same intent. While it is front-loaded with usage context, the duplication could be streamlined. It is still clear and not overly verbose.

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

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

Given the simplicity of the tool and the absence of an output schema, the description covers all necessary context: what it does, when to use it, and prerequisites (no API key, requires author name). It fully equips an agent to invoke the tool correctly without missing critical 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?

The schema already provides descriptions for all three parameters (body, post_id, author_name). The description mentions 'Requires an author name' but that is redundant with the schema's required field. It does not add any extra meaning to the parameters themselves, so it does not go beyond the schema's coverage.

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

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

The description clearly states the tool's purpose: adding a comment to a feature request on a public VoteShip board. It uses a specific verb ('add') and resource ('comment to a feature request'), and explicitly mentions 'public context' or 'follow-up', distinguishing it from other actions. The description is unambiguous and directly tells the agent 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 states when to use the tool: when the user wants to add public context or a follow-up to a known VoteShip feature request. It also mentions that no API key is needed and that an author name is required, which are important operational prerequisites. This clearly differentiates it from browsing, submitting, or upvoting (the sibling 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 and idempotent. The description adds useful behavioral context: no API key needed, posts sorted by vote count, and an interactive board render. 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?

The description is front-loaded with a 'Use this when' clause and keeps the total length reasonable. Some redundancy exists between 'inspect, compare, or interact' and 'View approved feature requests', but it remains efficient.

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

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

Given the output schema exists and annotations cover safety, the description provides enough context: public board, no auth, sorting behavior, and rendering. Nothing critical is missing for an AI agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the single parameter (project_slug) is fully documented there. The description adds no additional parameter semantics, so 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?

The description clearly states the tool browses and views approved feature requests on a public board, with specific verbs and resource. It doesn't explicitly name sibling tools for differentiation, but the contrast with write operations (add_public_comment, submit_feature_request, upvote_post) is implicit.

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

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

Provides an explicit trigger ('Use this when the user wants to inspect, compare, or interact with approved requests'), which gives clear context for when to use it. It doesn't mention alternatives or exclusions, 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?

Discloses key behavioral traits beyond annotations: the post is created as PENDING and requires board owner approval, no API key is needed, and metadata.source should identify the agent. The annotations (all false) provide almost no behavioral information, so the description carries the burden and does so thoroughly.

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 'Use this when...', and each sentence adds distinct value: usage trigger, action, auth, pending status, and metadata instruction. 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?

Given the output schema and 100% parameter coverage, the description sufficiently covers the usage context, auth requirement, approval workflow, and metadata instruction. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description's instruction to 'include metadata.source' points to the 'source' parameter but adds no new meaning beyond its schema description.

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

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

States a specific verb 'submit' and resource 'feature request to any public VoteShip board'. The phrase 'send new product feedback' clarifies the use case and distinguishes this from sibling tools (comment, upvote, browse) without naming them.

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

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

Explicitly states when to use: 'when the user wants to send new product feedback...' and adds the context 'without administering the project' and 'No API key needed.' However, it doesn't name alternative sibling tools or exclusion scenarios, so it's clear but not exhaustive.

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 goes beyond annotations: it explains the toggle behavior (adding and removing), the deterministic anonymous ID mechanism, and that no API key is needed. These are behavioral details not captured in the annotations, which only mark destructiveHint. The description also clarifies identity consistency, which is valuable for the agent.

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

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

The description is three sentences, each adding value: usage condition, toggle behavior, and identity mechanism. It is front-loaded with the most critical information (when to use) and avoids redundant details. No wasted words.

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

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

The description is quite complete for a simple tool with one parameter and an output schema. It covers identity, security (no API key), and the toggle nature. The only minor gap is that it doesn't state what the response contains, but the output schema presumably handles that. Given the simplicity and annotations, 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?

The schema already provides 100% coverage for the single parameter (post_id). The description does not add significant detail beyond the schema, but it does imply that the post_id must refer to a known post, which is a minor contextual addition. Baseline 3 is appropriate because the schema fully documents the 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 clearly states the tool's purpose: to add or remove a vote on a specified VoteShip post, with a toggle behavior. It distinguishes itself from siblings by mentioning the specific resource type (VoteShip post) and the action (vote/unvote), which is not covered by siblings like submit_feature_request or browse_board.

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

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

The description explicitly states when to use this tool: 'when the user explicitly wants to add or remove their agent identity's vote on a known VoteShip post.' It also implies when not to use it by scoping to voting only, and mentions the alternative (submit_feature_request) indirectly by distinguishing vote from submission. The condition 'known post' gives clear usage context.

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