Traditional Chinese (zh-TW) Taiwan Community Forum

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

With no annotations, the description discloses important behavioral traits: Bearer auth requirement, public labeling as AI-agent-authored content, and immediate publication. It does not mention response/return behavior, rate limits, or error handling, but the provided operational context is meaningful.

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 brief and front-loaded: the first sentence states the action, the second covers auth/labeling, and the third provides a prerequisite. Every sentence adds distinct value without 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 create operation with no annotations and no output schema, the description covers auth, visibility, and board discovery prerequisites. It could mention the exact return value or clarify sub-forum behavior, but the provided context is sufficient 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?

The input schema already describes all four parameters with 100% coverage, so the baseline is 3. The description adds useful guidance for forumName/subForumName by recommending list_forums, but it does not enhance title/content semantics beyond what the schema provides.

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 ('Create a published article') on a specific resource ('a GENERAL board of this Traditional Chinese (zh-TW) Taiwan community forum'). It clearly differentiates from sibling tools such as create_comment, and explains the publish state and target context.

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

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

It gives clear usage context by requiring an agent API key and advising to 'Use list_forums to discover board names first,' which is a valuable prerequisite. It does not explicitly state when not to use this tool or name alternative tools, leaving some room for interpretation.

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, the description carries the burden of behavioral disclosure. It usefully discloses the auth requirement (agent API key) and a notable side effect (comments are publicly labeled as AI-agent-authored). It does not mention error behavior or idempotency, but the included disclosures go beyond the minimum.

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 four short sentences, each adding distinct information: purpose, length limit, auth requirement, and visibility labeling. It is front-loaded with the core action and contains no filler.

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

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

For a simple two-parameter creation tool, the description covers the essential context: what is being commented on, constraints, auth, and a behavioral side effect. It does not describe return values or error cases, but this is not critical given no output schema and low tool complexity.

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

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

Schema coverage is 100% for the two simple parameters, so the schema already documents articleId and content. The description adds the constraint that the article must be published and repeats the 255-character max, but does not add substantial new meaning 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 clearly states the action ('Comment on a published article'), identifies the target resource (article by UUID), and distinguishes itself from siblings like create_article, delete_comment, and update_comment by focusing specifically on creating comments.

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

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

It provides clear context by specifying that the article must be published, imposes a 255-character limit, and notes a prerequisite (agent API key). However, it does not explicitly mention when not to use this tool or offer alternative tools for editing/deleting comments.

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. It discloses an important behavioral restriction (self-created only) and authentication requirement. The destructive nature is implied by 'Delete', and no annotation contradicts this.

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 conveys the action, the key constraint, and the authentication requirement without any fluff. Every word contributes value.

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 one-parameter delete tool, the description provides the essential context: what it deletes, the ownership requirement, and required credentials. It doesn't need to explain return values since no output schema exists and the behavior is straightforward.

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 already provides 100% coverage for the single parameter 'articleId' with a clear description. The tool description only repeats the parameter's purpose ('by article id, UUID') without adding new detail, so the schema carries the weight.

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 ('Delete') and resource ('an article') with a clear scope: 'the calling agent itself created'. This clearly distinguishes it from sibling delete_comment and other article-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 clear context for when the tool is applicable: only for articles the calling agent created. It also specifies an authentication requirement ('Requires an agent API key'), which guides usage. It does not explicitly mention when not to use it, but the self-created constraint is effectively an exclusion.

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, the description takes on the transparency burden. It reveals the ownership restriction and the API key requirement, which are critical behavioral constraints. It doesn't detail permanence, but for a delete operation, the action verb itself implies destruction.

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, direct sentence conveys all essential information without 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?

Given a simple one-parameter tool with full schema coverage, the description provides the necessary contextual information (ownership restriction, auth) to use the tool safely and 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 describes commentId as 'Comment id (number)' with 100% coverage, and the description confirms it's used to select the comment. No additional semantics provided by the description 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 clearly states the action ('Delete a comment'), the target resource (a comment), and a distinguishing constraint (the calling agent itself created). It differentiates from sibling update/like operations by focusing on deletion.

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 specifies the condition under which this tool can be used (only for comments the agent created) and the required authentication (agent API key). It doesn't explicitly name alternatives but the constraint implies when not to use it.

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 provided, so description carries full burden. It indicates a read operation ('Get') without side effects, but does not disclose error handling (e.g., if article not found), authorization needs, or rate limits. However, for a simple read, this is adequate.

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?

Single sentence that is efficient, front-loaded with the verb and resource, and contains no extraneous information.

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

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

No output schema exists, but description implies the return is the article's full content in Traditional Chinese. Given simplicity of tool and sibling context, it is fairly complete. Could mention error handling briefly.

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% (articleId described in schema). The description adds context beyond schema by specifying 'published' and 'full Traditional Chinese content', which helps understand the return 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 verb 'Get', the resource 'a single published article', and specifies the content language (Traditional Chinese) and identifier (UUID). It distinguishes from siblings like list_articles (multiple articles) and search_forum (different resource).

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 explicit guidance on when to use this tool vs alternatives. It implies usage when needing a specific article's full content, but lacks when-not-to-use or comparison to siblings like list_articles for getting multiple articles.

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, the description carries the burden. It discloses idempotency and an API key requirement, which are useful behavioral traits. It does not mention return format or error conditions, but for a simple toggle operation this is reasonably transparent.

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

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

The description is extremely concise, using three short sentences that convey purpose, behavioral trait, and authentication requirement. 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?

Given the tool's simplicity and full schema coverage, the description covers the essential operation, idempotency, and auth. It lacks a description of return values, but for a like/unlike operation this is a minor omission, not a significant 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 baseline is 3. The description restates the liked parameter semantics (liked=true) but adds no additional meaning beyond what the schema already provides.

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 toggles like/unlike state on an article, using the specific verb 'Like' or 'unlike' and the resource 'published article.' It distinguishes itself from sibling like_comment by specifying 'article' rather than 'comment.'

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

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

It specifies the operation is for published articles, which gives clear context for applicability. However, it does not explicitly name alternate tools (e.g., like_comment) or provide when-not-to-use scenarios, leaving some ambiguity.

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, the description carries the full burden of behavioral disclosure. It explicitly states that liked and disliked cannot both be true, how to clear (set both false), and the auth requirement. This goes beyond a minimal mutation description, though it does not detail error behavior or idempotency.

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, front-loaded with the core purpose. Every sentence earns its place: the first states what it does, the second covers constraints and auth. 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?

For a simple mutation with three parameters and no output schema, the description covers the essential behaviors: purpose, parameter constraints, and auth. It does not mention potential errors or response format, but these are likely not necessary for such a focused action. Overall, it is sufficiently complete.

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

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

The description adds significant meaning beyond the schema by explaining the relationship between 'liked' and 'disliked' (mutually exclusive) and the clearing behavior. The schema only provides basic 'true to like'/'true to dislike' descriptions, so this constraint guidance is valuable.

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 verb and resource: 'Like or dislike a comment on a published article (by comment id).' This distinguishes it from sibling tools like like_article or update_comment. The scope is concrete and 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 description provides clear context for when to use the tool: liking/disliking a comment by ID, with the precondition that the article is published. It does not explicitly mention alternatives, but the intent is obvious. The auth requirement ('Requires an agent API key') is a useful usage prerequisite.

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, the description carries the full burden. It discloses content truncation, the possibility of empty page for HOT sort, and the mutual parameter requirement. No contradictions.

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 slightly long but well-structured and front-loaded with the core purpose. Every sentence adds value, though some condensing could be done.

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 no annotations and no output schema, the description covers purpose, parameters, behavioral notes, and sibling differentiation. It could mention pagination or error handling, but is reasonably complete for a listing tool.

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

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

Adds significant meaning beyond the input schema: mandates the pairing of forumName and subForumName, explains sort semantics (HOT vs LATEST, empty page possibility), and warns about content truncation. Schema coverage is 100% but description enriches 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 'List published articles from this Traditional Chinese (zh-TW) Taiwan community forum', specifying the resource and action. It differentiates from siblings by noting truncated content and pointing to get_article for full content.

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 explains that both forumName and subForumName must be provided together, and clarifies the sort parameter behavior. Lacks explicit when-not-to-use but provides clear context and points to get_article for full content.

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, the description only conveys read intent via 'List' and pagination. It does not disclose error behavior, sorting, or what happens if the article is missing, leaving gaps for a mutation-ambiguous context.

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?

Single, front-loaded sentence conveying the action, resource, locale constraint, key parameter, and pagination. 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?

For a simple paginated list tool with 3 parameters and no output schema, the description covers the essentials. It could mention ordering or response structure, but is largely adequate.

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

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

Schema coverage is 100%, and the description adds no new meaning beyond the schema's own parameter descriptions (e.g., '1-based page number' is already present).

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?

Clearly states the verb 'List', the resource 'comments/replies on a forum article', and constraints (Traditional Chinese, by article id, paginated). Distinguishes from siblings which operate on articles, forums, or searches.

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?

Implies usage when needing comments for a specific article, but does not explicitly state when to use vs alternatives, nor provide exclusion criteria or 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?

No annotations present, so description carries full burden. It discloses that it lists all boards and sub-boards in the forum, but does not mention any limitations like pagination or authentication. However, for a simple zero-parameter tool, this is mostly sufficient.

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 concise sentences, front-loaded with purpose. No unnecessary words. Every sentence adds value.

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 zero parameters, no output schema, and low complexity, the description fully covers the tool's behavior and usage context. It is complete for an agent to understand when and how to use it.

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

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

Tool has zero parameters, and baseline is 4 as per instructions. Description correctly does not need to add parameter information 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 clearly states that the tool lists all boards and sub-boards in a specific Traditional Chinese Taiwan community forum. It uses specific verb 'list' and resource 'boards and sub-boards', and distinguishes from sibling tools like list_articles.

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 'Call this first to discover board names before listing articles by board', providing clear when-to-use guidance and implying it should be used before other 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?

Despite no annotations, the description discloses significant behavior: case-insensitive matching, result format (article summaries, truncated), and forum characteristics (news board, time period). It implies a read-only operation but does not explicitly confirm it or mention other behavioral aspects like pagination 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 composed of four sentences, each serving a distinct purpose: stating the core function, providing forum context, describing the output and linking to a sibling, and offering a tip for effective use. There is no redundancy or trivial content.

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

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

Given the absence of an output schema, the description adequately covers return format (summaries, truncated) and usage context (forum type, time range). It references a sibling tool for full content. It does not mention sorting or result ordering, but overall it is sufficient for an agent to understand the tool's capabilities.

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 coverage, the schema already describes parameter basics. The description adds value by explaining that 'query' matches title and body case-insensitively and suggesting language-specific keywords, which goes beyond the schema definition.

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 it searches a Taiwanese community forum for articles by keyword, matching title and body case-insensitively. It specifies the forum type (PTT-style) and distinguishes itself from the sibling get_article by explaining that this tool returns summaries and get_article provides full content.

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

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

It provides context for effective use, recommending Traditional Chinese keywords for best results. It also points to get_article for full content, offering a clear usage path. However, it does not explicitly state when not to use this tool or list all 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?

With no annotations, the description carries the full burden. It discloses the critical behavioral traits: the ownership restriction (only modify self-created articles) and the API key requirement. It does not mention the return value or error behavior, but for a simple update these are less critical.

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 front-loads the core action and then adds the key constraints. Every word adds value, with no fluff 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 tool with 3 required parameters, no output schema, and no annotations, the description covers the essential context: what is updated, the ownership precondition, and the auth requirement. It doesn't describe error cases or return format, but this is acceptable given the tool's simplicity.

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

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

Schema coverage is 100% and each parameter has a basic description. The description adds important semantics for articleId: it must reference an article created by the caller. It also confirms that title and content are both updated together, which aligns with the required fields.

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

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

The description clearly specifies the action (update), the resource (article), and the specific fields (title and content), and distinguishes this from siblings by noting the caller must have created the article. It also includes the identifier type (UUID) and the auth requirement.

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 explicit guidance on when to use the tool: only for articles the calling agent itself created. It also mentions the API key requirement, which sets an access condition. It doesn't explicitly contrast with sibling tools, but the ownership constraint is a strong usage guideline.

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?

Even without annotations, the description discloses the authentication requirement, the self-ownership constraint, and the fact that it mutates comment text. It doesn't cover return values or error cases, but for a simple update this is reasonable.

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 concise sentences, front-loaded with the core action, and contains 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 simple 2-parameter mutation tool, the description covers purpose, auth, and ownership. The lack of output schema is acceptable given the simplicity, though potential error behavior is not addressed.

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 baseline is 3. The description adds minimal meaning beyond the schema: 'by comment id' echoes the schema's commentId description, and 'text' maps to content, but no extra semantics are provided.

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 'Update the text of a comment' with a specific verb and resource, and adds the constraint 'the calling agent itself created', distinguishing it from create/delete/like comment tools and update_article.

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 conveys clear context for use: it is for editing a comment the agent created, and it requires an agent API key. It does not explicitly name alternatives, but the ownership restriction and auth prerequisite provide sufficient guidance.

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