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

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Add' implies a write/mutation operation, it doesn't specify whether this requires authentication, what happens if the upvoter already exists, if there are rate limits, or what the response looks like. This leaves significant behavioral gaps for a mutation tool.

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

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

The description is a single, efficient sentence that states the core functionality without any wasted words. It's appropriately sized for the tool's complexity and gets straight to the point.

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

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

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after adding an upvoter, what the return value might be, or address potential error conditions. Given the complexity of a write operation, more contextual information is needed.

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 input schema has 100% description coverage, with clear documentation for all three required parameters (id, email, name). The description doesn't add any parameter-specific information beyond what's already in the schema, so it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Add') and target resource ('an upvoter to a post'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_post_upvoters' or explain what distinguishes adding an upvoter from other post-related operations.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'get_post_upvoters' or 'update_post'. There's no mention of prerequisites, appropriate contexts, or exclusions, leaving the agent with insufficient usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates comments or replies, implying a write operation, but fails to mention permissions required (e.g., admin rights for private comments), rate limits, or what happens on success/failure. This leaves significant gaps for a mutation tool.

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

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

The description is a single, efficient sentence with zero waste—'Create a new comment or reply'—front-loading the core purpose without unnecessary details. Every word earns its place, making it highly concise and well-structured.

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

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

For a mutation tool with 8 parameters, no annotations, and no output schema, the description is inadequate. It lacks context on permissions, behavioral traits, error handling, and output expectations, leaving the agent under-informed despite the detailed schema. More completeness is needed for safe and effective use.

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 8 parameters thoroughly. The description adds no additional meaning beyond implying 'comment or reply' relates to 'parentCommentId', but this is already clear in the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the action ('Create') and resource ('comment or reply'), distinguishing it from sibling tools like 'update_comment' or 'delete_comment'. However, it doesn't specify the context (e.g., on submissions or changelogs) or differentiate from 'create_post', making it slightly less specific than ideal.

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 like 'create_post' or 'update_comment', nor does it mention prerequisites such as needing a submissionId or changelogId. The description lacks explicit usage context or exclusions, leaving the agent to infer from parameters alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Create a new post' implies a write operation, but it doesn't disclose permissions needed, whether it's idempotent, rate limits, or what happens on failure. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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 extremely concise with 'Create a new post'—a single, front-loaded sentence that wastes no words. It's appropriately sized for its purpose, though this conciseness comes at the cost of detail in other dimensions.

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 complexity (10 parameters, mutation tool, no output schema, and no annotations), the description is incomplete. It doesn't explain return values, error handling, or behavioral traits, relying solely on the schema for parameters. For a creation tool with significant input requirements, more context is needed.

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 input schema has 100% description coverage, so the schema already documents all 10 parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., no context on how parameters interact or default behaviors). Baseline 3 is appropriate when 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 'Create a new post' clearly states the action (create) and resource (post), which is adequate. However, it doesn't differentiate this from sibling tools like 'update_post' or specify what type of post (e.g., forum post, blog post), leaving it somewhat vague. It's not tautological but lacks specificity.

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

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

The description provides no guidance on when to use this tool versus alternatives. There are sibling tools like 'update_post' and 'list_posts', but the description doesn't mention prerequisites, context (e.g., for new content creation), or exclusions, offering only a basic statement without usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively reveals a key trait: the deletion may be 'soft' (not permanent) when the comment has replies, which is crucial for understanding side effects. However, it doesn't cover other aspects like permissions needed, error conditions, or what 'soft delete' entails operationally.

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 front-loads the core action ('Delete a comment') and immediately adds the critical behavioral detail ('soft delete if has replies'). There is zero waste, and every word earns its place by providing essential context.

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

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

Given the tool's complexity (a mutation with conditional behavior), no annotations, and no output schema, the description is minimally adequate. It covers the core action and a key behavioral trait, but lacks details on permissions, error handling, or return values, leaving gaps for the agent to infer.

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 input schema has 100% description coverage, with the 'id' parameter clearly documented. The description adds no additional meaning about the parameter beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.

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 specific action ('Delete a comment') and distinguishes it from siblings like 'update_comment' or 'delete_post' by specifying the resource type. It goes beyond a simple verb by adding the conditional behavior ('soft delete if has replies'), which further clarifies its unique purpose.

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

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

The description implies usage for deleting comments, but provides no explicit guidance on when to use this tool versus alternatives like 'update_comment' or other deletion tools. It mentions a condition ('if has replies') that affects behavior, but doesn't state when to choose this over other options or any prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'permanently' which hints at irreversibility, but doesn't address permissions needed, error conditions, side effects, or what happens to associated data (e.g., comments). For a destructive operation, this leaves significant gaps in understanding its 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?

The description is a single, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it immediately understandable.

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 destructive tool with no annotations and no output schema, the description is inadequate. It doesn't explain what 'permanently' entails operationally, what the response looks like, or error handling. Given the complexity of deletion operations, more context is needed for safe use.

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 input schema has 100% description coverage, with the 'id' parameter clearly documented. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline for high schema coverage without compensating value.

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 action ('Delete') and target resource ('a post'), with the adverb 'permanently' adding specificity about the nature of the deletion. However, it doesn't explicitly differentiate from sibling tools like 'delete_comment' or 'update_post' beyond the resource name.

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 like 'update_post' or 'delete_comment', nor any prerequisites or contextual constraints. The description only states what the tool does, not when it should be selected.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It lists available fields but doesn't explain key behaviors: whether this is a read-only operation, if it requires authentication, how pagination works (implied by limit/page but not described), error handling, or rate limits. The field list adds some context but misses critical operational details for a tool with 9 parameters.

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 the core purpose but becomes overly verbose by listing all available fields twice (including nested replies). This repetition (e.g., field names duplicated for replies) adds unnecessary length without enhancing clarity. A more concise approach would summarize field categories or refer to documentation.

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

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

Given the tool's complexity (9 parameters, no output schema, no annotations), the description is incomplete. It lacks information on return format, error cases, authentication needs, and behavioral constraints. While it covers fields and basic purpose, it doesn't provide enough context for safe and effective use by an AI agent, especially for a data retrieval tool with filtering options.

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 description coverage is 100%, so the schema already documents all 9 parameters thoroughly. The description adds value by listing available return fields (e.g., upvoted, content, replies), which helps interpret the 'select' parameter, but doesn't provide additional semantic context beyond what the schema offers. This meets the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Get comments for a post or changelog.' It specifies the resource (comments) and the target objects (post or changelog). However, it doesn't explicitly differentiate from sibling tools like 'get_post_upvoters' or 'list_posts,' which reduces the score from a perfect 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a post or changelog ID), compare to siblings like 'list_posts' for post retrieval, or specify use cases (e.g., filtering vs. fetching all comments). This lack of contextual direction leaves the agent to infer usage.

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

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

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a read-only operation ('Get list') but doesn't disclose pagination behavior (implied by 'page' and 'limit' parameters), rate limits, authentication needs, or error conditions. For a tool with 3 parameters and no annotation coverage, this leaves significant gaps.

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

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

The description is a single, efficient sentence with zero waste—every word contributes to understanding the tool's purpose. It's front-loaded and appropriately sized for a straightforward retrieval tool, making it easy for an agent to parse quickly.

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

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

Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is minimally adequate. It covers the core purpose but lacks context on usage, behavioral traits, or output format. Without annotations or output schema, the agent must rely on the schema and inference, leaving room for error in 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 description coverage is 100%, so the schema fully documents parameters (submissionId, page, limit). The description adds no additional meaning beyond implying the tool operates on a post (via 'post' in the text), which aligns with the schema's 'Post ID'. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the verb ('Get list') and resource ('users who upvoted a post'), making the tool's purpose immediately understandable. It distinguishes from siblings like 'get_comments' or 'list_posts' by focusing specifically on upvoters. However, it doesn't explicitly contrast with 'add_upvoter' (which adds rather than retrieves upvoters), keeping it from a perfect 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid post ID), exclusions, or comparisons to siblings like 'get_comments' for post-related data. The agent must infer usage from the name and schema alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool finds similar posts but doesn't explain how similarity is determined (e.g., semantic matching, keywords), what the output format is (e.g., list of posts with scores), or any limitations like rate limits or authentication needs. This is a significant gap for a search tool with zero annotation coverage.

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, clear sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for the tool's complexity, making it easy to parse quickly.

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 lack of annotations and output schema, the description is incomplete. It doesn't cover behavioral aspects like how similarity is computed, output format, or usage context relative to siblings. For a search tool with no structured data beyond the input schema, more detail is needed to guide effective agent use.

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 both parameters ('query' and 'locale') adequately. The description adds no additional meaning beyond what the schema provides, such as examples of query formats or locale usage. This meets the baseline for high schema coverage but doesn't enhance parameter understanding.

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 ('Find') and resource ('posts similar to the given query text'), making the purpose understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'list_posts' or 'resolve_post_slug', which might also involve post retrieval. A perfect score would require clarifying how 'similar' differs from general listing or resolution.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing an existing post or query context, or differentiate from siblings like 'list_posts' for general listing or 'resolve_post_slug' for specific post lookup. This leaves the agent with minimal context for tool selection.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. While 'List posts' implies a read operation, there's no information about pagination behavior (beyond the limit/page parameters), rate limits, authentication requirements, or what happens when no filters are applied. The description merely lists available fields without explaining behavioral characteristics.

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 followed by a long field list. While the initial sentence is concise, the exhaustive field enumeration feels like data dumping rather than helpful guidance. The structure could be improved by grouping related fields or explaining field relationships rather than just listing them.

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 10-parameter tool with no annotations and no output schema, the description is insufficient. It doesn't explain the return format, pagination behavior, error conditions, or typical response structure. The field list hints at what might be returned, but without an output schema, the description should provide more complete context about the tool's behavior and results.

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 input schema already documents all 10 parameters thoroughly. The description adds marginal value by listing available return fields, but doesn't provide additional semantic context beyond what's in the parameter descriptions. This meets the baseline for high schema coverage.

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

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

The description states 'List posts with optional filtering' which clearly indicates the verb (list) and resource (posts). However, it doesn't distinguish this from sibling tools like 'get_similar_submissions' or 'get_post_upvoters' - it's a generic listing function without specifying what makes it unique among the available post-related tools.

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

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

The description provides no guidance on when to use this tool versus alternatives. There's no mention of when to choose list_posts over get_similar_submissions or get_post_upvoters, nor any context about prerequisites or typical use cases. The agent must infer usage from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool converts a slug to an ID and gets details, implying a read operation, but doesn't cover critical aspects like error handling (e.g., invalid slugs), authentication needs, rate limits, or the format of returned details. This is a significant gap for a tool with no annotation coverage.

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 extremely concise and front-loaded, consisting of a single, clear sentence that directly states the tool's function. Every word earns its place, with no redundant or vague language, making it efficient for quick understanding by an AI agent.

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 complexity (a lookup tool with no output schema) and lack of annotations, the description is incomplete. It doesn't explain what 'post details' include, how errors are handled, or any behavioral traits, leaving the agent with insufficient information for reliable invocation. This is inadequate for a tool that retrieves data without structured output documentation.

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 the input schema fully documenting the 'slug' parameter, including an example. The description adds minimal value beyond this, as it only mentions 'post slug' without providing additional context like format constraints or usage tips. Since the schema does the heavy lifting, the baseline score 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 the tool's purpose: converting a post slug to a post ID and retrieving post details. It specifies the verb ('convert' and 'get') and resource ('post slug' to 'post ID and post details'), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_post_upvoters' or 'list_posts', which might also retrieve post information, so it doesn't reach the highest 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid slug), exclusions, or compare it to siblings like 'list_posts' or 'get_post_upvoters'. This leaves the agent without context for tool selection, relying solely on the description's implied use case.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Update an existing comment', implying a mutation operation, but doesn't cover critical aspects like required permissions, whether updates are reversible, rate limits, or what happens to unspecified fields. This is inadequate for a mutation tool with zero annotation coverage.

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

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

The description is a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for the tool's purpose, earning its place without unnecessary elaboration.

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

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

Given the tool's complexity (mutation with 6 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral nuances, leaving significant gaps for an AI agent to understand how 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 fully documents all 6 parameters (e.g., 'id' as Comment ID, 'content' as New content). The description adds no parameter-specific information beyond what's in the schema, meeting the baseline of 3 where 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 'Update an existing comment' clearly states the action (update) and target resource (comment), but it's vague about scope and doesn't differentiate from sibling tools like 'update_post' or 'create_comment'. It lacks specificity about what aspects can be updated or the context of the comment system.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing comment ID), exclusions, or comparisons to siblings like 'create_comment' for new comments or 'delete_comment' for removal. Usage context is implied but not explicit.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. 'Update an existing post' implies a mutation operation but doesn't specify permissions required, whether changes are reversible, rate limits, error conditions, or what happens to fields not mentioned in the update. For a mutation tool with 11 parameters and no annotation coverage, this is inadequate.

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

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

The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a basic tool description and front-loads the core purpose immediately. Every word 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 mutation tool with 11 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain the update behavior (partial vs. full updates), response format, error handling, or how it differs from sibling tools. The agent lacks critical context to use this tool effectively beyond basic parameter passing.

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 parameters are documented in the schema itself. The description adds no additional meaning about parameters beyond what's in the schema (e.g., no explanation of how partial updates work, default behaviors, or relationships between fields). Baseline 3 is appropriate 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?

The description 'Update an existing post' clearly states the verb ('Update') and resource ('post'), but it's vague about scope and doesn't distinguish from sibling tools like 'update_comment' or 'create_post'. It doesn't specify what aspects of a post can be updated or the tool's specific role in the post management ecosystem.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'create_post', 'delete_post', or 'update_comment'. There's no mention of prerequisites (e.g., needing an existing post ID), appropriate contexts, or exclusions. The agent must infer usage from the tool name alone.

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