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

No annotations provided, so description carries full burden. Discloses side effect: 'Pauses current task if assignee is already working on another.' Also mentions required board stage. Does not cover authorization, error scenarios, or return values, but the core behavioral impact is conveyed.

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: first states purpose, second adds precondition. No unnecessary words. Every sentence earns its place. Highly 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?

For a tool with no annotations and no output schema, the description covers purpose, side effect, and a critical precondition. It lacks error conditions and return value hints, but given the simplicity of the action (start tracking), it is mostly 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?

Schema coverage is 100% with clear descriptions: 'Task ID' and 'Assignment ID (from task.assignments[].id)'. The description adds extra context for assignment_id by specifying its source. This goes beyond the schema, adding value. Baseline 3, plus 1 for the added detail.

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?

Starts with 'Start tracking work on a task (play).' Clearly states verb (start tracking) and resource (work on a task). The 'play' term is explained as tracking. No sibling tools overlap, so distinct purpose is clear.

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 a precondition: 'Always ensure that the task is in the Ongoing column (board_stage_id: 96356) before calling this tool.' This guides when the tool should be used. However, it does not mention when not to use it or provide 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?

No annotations provided, and description only states the action without disclosing side effects, permissions, or reversibility; minimal behavioral 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?

Single sentence of 10 words, directly stating the purpose with no 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?

Lacks information on return values, error handling, or prerequisites; insufficient for a mutation tool with no output schema or annotations.

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 baseline is 3. Description adds no extra meaning beyond the schema's parameter descriptions.

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?

Description clearly states the action 'Add a reaction (emoji) to a comment' with specific verb and resource, distinguishing it from sibling comment 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?

No guidance on when to use this tool versus alternatives; lacks context for selecting among comment-related or 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?

No annotations are provided, so the description carries the full burden. It discloses the format constraints (no Markdown), the optional evidence capture workflow (capture, upload, append to text), and the required order of operations. It does not mention potential side effects (e.g., notifications) or return values, but for a creation tool, the key behaviors are well 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?

The description is highly concise: two sentences, the first covering purpose and format, the second outlining the evidence capture steps in a clear, bullet-point-like structure. Every sentence serves a purpose with no redundancy.

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

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

The tool has 4 parameters, 2 required, no output schema. The description covers the main creation behavior, format constraints, and the complex optional workflow. It does not explain behavior when only one of url_antes/url_depois is provided, nor does it mention error handling or response format, but overall it is sufficiently complete for a creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the format of 'text' (plain text and raw URLs only, no Markdown) and the conditional behavior of 'url_antes' and 'url_depois' (when both are provided, trigger evidence capture). This goes beyond the schema descriptions.

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 'Create a comment on a task in Runrun.it' with specific details about format (plain text and raw URLs only) and an optional evidence capture workflow using url_antes and url_depois. This distinguishes it from sibling tools like runrunit_get_comment, runrunit_update_comment, and runrunit_delete_comment by highlighting a unique behavior.

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 context for when to use the tool, especially the multi-step evidence capture process when both url_antes and url_depois are provided. However, it does not explicitly state when not to use this tool versus alternatives like runrunit_update_comment or runrunit_create_external_comment, 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?

No annotations are provided, so the description carries the full burden. It discloses the no-Markdown constraint, which adds value beyond the schema. However, it does not detail other behavioral aspects such as authentication requirements, rate limits, or side effects.

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, directly stating the purpose and a key usage constraint. It is efficient and front-loaded with essential information, with no unnecessary 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 tool is simple with two required parameters and no output schema. The description covers the purpose and text format but does not explain what the response will be (e.g., comment ID or success status). For a creation tool, this is a 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 coverage is 100%, but the description adds the meaningful constraint that the text must be simple and without Markdown, which the schema's 'Comment text' does not convey. The task_id parameter is not elaborated 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?

Clearly states the tool creates a comment in the external/guest channel on a task, specifically for sharing with external clients. This distinguishes it from the sibling 'runrunit_create_comment' which likely handles internal 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?

Explicitly states the tool is for comments shared with external clients and specifies the channel name. It also notes the constraint of using simple text without Markdown. However, it does not explicitly mention when not to use or provide alternatives like the internal comment tool.

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 explains the default board, column, assignee behavior, and the special handling of the description parameter (appended via Task Description API, never replacing existing text). This adds useful context beyond basic creation, though it does not mention rate limits or auth requirements.

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 paragraph that starts with the core purpose, then required fields, then optional ones. Every sentence adds value, and there is no wasted text.

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

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

Given no output schema, the description omits return value details (e.g., whether the created task object is returned). However, it covers defaults, parameter behavior, and optional fields thoroughly. The 'etc.' at the end is slightly vague but acceptable.

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%, but the tool description adds significant meaning: it explains default values (board, column, assignee), the title format hint, and the appending behavior for description. This goes far beyond mere schema descriptions.

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 'Create' and resource 'task', specifies default board (Ongoing with ID 96356), default column (Task), and default assignee (the caller). This distinguishes it from sibling tools like runrunit_update_task and runrunit_delete_task.

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 lists required fields (title, type_id) and optional ones, giving an example title format. It implies the tool is for creating tasks in the specified default board/column, but does not explicitly say when not to use it or mention alternatives for other boards (though no other create task tool exists among siblings).

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 bears full responsibility for behavioral disclosure. It states the action (create) and a consequence ('starts tracking eligibility'), but gives no details on reversibility, error behavior, permissions, or side effects. For a mutation tool, this is minimal and insufficient for an agent to assess risks or outcomes.

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 conveys the core action and a key condition. No redundant information, no filler. It is efficiently front-loaded with the verb and purpose.

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?

Despite low complexity (1 param, no output schema), the description omits crucial context: what the tool returns on success, possible error scenarios when conditions are not met, or any further behavioral details. Without an output schema, the description should at least indicate the result format or state after creation. The provided information is too sparse for a complete understanding.

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 sole parameter 'task_id' is fully described in the schema with description 'Task ID', so schema coverage is 100%. The description does not add new semantic details about the parameter beyond the schema, but the prerequisite conditions (task state) provide indirect context. 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 tool creates a workflow for a task and mentions it starts tracking eligibility. The verb 'create' and resource 'workflow for a task' are specific. However, it does not distinguish this tool from sibling tools that also deal with task-related workflows or creation actions, missing explicit differentiation.

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 conditions for use: 'Task must not be closed, ongoing, or already have a workflow.' This tells the agent when to use this tool versus not. However, it does not name alternative tools for cases where the task already has a workflow or is in an unsuitable state, so it lacks explicit cross-referencing.

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 must disclose behavioral traits. It only says 'delete' but does not specify permanence, side effects (e.g., cascading deletion of replies), or authorization requirements. The behavioral impact is implied but not detailed.

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 short sentence, which is concise but sacrifices necessary detail. It is front-loaded but overly minimal; it could include more context without becoming 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?

For a simple delete tool with one parameter and no output schema, the description provides the bare minimum. It omits important context such as irreversibility, error handling, and what happens to associated data, making it incomplete for safe agent 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?

The input schema has 100% coverage (the only parameter 'id' is described as 'Comment ID'). The tool description adds no extra meaning beyond the schema, so it meets the baseline expectation for a high-coverage 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) and the resource (comment on Runrun.it). However, it does not distinguish it from sibling tools like runrunit_create_comment or runrunit_update_comment, though the verb 'delete' naturally differentiates it.

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, no prerequisites, and no caution about the irreversible nature of deletion. It simply states the action without any hints for effective use.

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

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

No annotations; description fails to mention destructive nature, permission requirements, or side effects (e.g., cascading deletions). Only states 'Delete'.

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, no fluff. Slightly too brief but not incomplete. Front-loaded with verb and resource.

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?

Lacks behavioral context, return value, error handling, or security notes. For a simple delete tool with one param, minimally acceptable but leaves many gaps.

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 parameter 'id' is described as 'Task ID' in schema. Description adds no extra meaning beyond the schema, meeting baseline for high 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?

Clearly states the verb 'Delete' and resource 'task on Runrun.it'. Distinct from siblings like create, update, get, etc.

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 no guidance on when to use this tool versus alternatives, no prerequisites, no conditions for deletion.

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?

Reveals that the tool avoids duplicate channels by comparing names and uses an environment variable for guild ID. Lacks information on return values, failure modes, or permissions needed, relying solely on the description since no annotations are provided.

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?

Description is concise with three clear sentences, front-loading the main action. No superfluous information, but could be slightly more streamlined by merging the last two sentences.

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?

Covers the creation logic reasonably well given no output schema, but omits behavior when channel already exists (whether it errors or returns existing). Also no mention of permissions or error handling, leaving gaps for effective 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?

Adds meaningful context beyond the schema: explains the naming convention (slug-like) and that guild_id can be omitted if DISCORD_GUILD_ID is set. Schema already covers parameters, but description enriches the 'name' parameter example and the 'one channel per client' pattern.

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 it creates a text channel in a Discord server, with idempotency condition. However, it does not differentiate itself from the sibling tool runrunit_discord_get_or_create_channel, which likely has similar functionality.

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 for creating a channel per client pattern, but does not explicitly state when to use this over alternatives like get_or_create_channel. No exclusion criteria mentioned.

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 the get-or-create behavior and the channel naming convention (slug from client_name). However, it does not mention error handling, permission requirements, or rate limits, which would be nice but not critical for this simple 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 two sentences plus a brief parenthetical, front-loaded with the core purpose and usage. Every sentence is necessary and no fluff. It is efficiently 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?

The description explains what the tool returns (channel_id and channel_name) despite no output schema. It covers the main behavior. However, it does not clarify behavior when multiple parameters are provided or omitted (e.g., if both client_id and client_name are given). Slight gap, but overall complete for a utility tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by instructing to transform client_name to a slug (e.g., 'Client 1' -> 'client-1'), providing guidance beyond the schema. This extra semantic detail justifies a 4.

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 'Get or create a Discord text channel for a Runrun.it client', specifying the verb and resource. It distinguishes from sibling tools like runrunit_discord_create_channel and runrunit_discord_send_message by indicating its idempotent behavior and intended use before sending messages.

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 instructs to 'Use before runrunit_discord_send_message to ensure the channel exists', providing clear when-to-use context relative to a sibling tool. Also implies when not to use it (e.g., for listing channels or creating a new distinct channel).

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

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

No annotations are provided, so the description must cover behavioral traits. It mentions using environment variables (DISCORD_GUILD_ID or DISCORD_CHANNEL_ID) but omits details like rate limits, permissions, or error handling.

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 with no fluff. Every word earns its place, providing essential information efficiently.

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 adequate for a simple tool with one optional parameter. However, it lacks details about the return format (e.g., list of channel objects) or any behavioral context beyond server identification.

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 already describes the guild_id parameter as optional. The description adds value by mentioning resolution from DISCORD_CHANNEL_ID, but this is a minor addition 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 'List channels in the Discord server' with a specific verb and resource. It distinguishes from sibling tools like 'runrunit_discord_create_channel' or 'runrunit_discord_send_message' by focusing on listing.

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 when needing to list channels but provides no explicit guidance on when to use versus alternatives. No exclusions or when-not-to-use context is given.

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 indicates a write operation but lacks details on idempotency, error handling, rate limits, or return behavior. With no annotations, more disclosure is needed.

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, each adding value: purpose, usage, requirements. 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?

Covers purpose, use cases, and prerequisites but omits output/response behavior and behavioral details like failure handling. Adequate but not fully comprehensive.

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?

All parameters have descriptions in the schema (100% coverage); the tool description adds no extra semantics beyond stating requirements.

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 'Send a message to a Discord channel' with specific use cases and distinguishes from sibling Discord channel management 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?

Provides explicit context ('execution history or notifications') and prerequisites ('requires BOT_RUNRUNIT_REPORT'), but does not explicitly mention when not to use or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states it's a 'get' operation but does not mention potential errors (e.g., if ID not found), authentication needs, or rate limits.

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

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

One efficiently worded sentence (10 words) front-loading the action and resource. 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?

For a simple get-by-ID tool, the description is adequate but minimal. It doesn't describe the return format or behavior when the comment does not exist. With no output schema, the agent would benefit from more detail.

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

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

Schema description coverage is 100%—the schema itself documents the 'id' parameter. The description adds no extra meaning beyond 'by ID', which is already implied by the parameter description. 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 states the verb 'Get', the resource 'single comment', and the retrieval method 'by ID'. It distinguishes from sibling tools like create, update, delete, and list_task_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?

No explicit guidance on when to use this tool versus alternatives like runrunit_list_task_comments (which lists many comments). The description does not mention prerequisites or 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 are provided, so the description carries full burden. It only states 'Get a single task by ID' without disclosing behavioral traits such as authentication requirements, rate limits, error handling for missing IDs, or response structure. This is insufficient for a mutation-free read 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?

One sentence, no wasted words. Front-loaded with verb and object. 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?

Tool is simple (one required param, no output schema). Description covers the essential action but omits return value information. Without an output schema, the agent has no hint about what data is returned.

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 additional meaning beyond the schema's 'Task ID' field. 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 states the verb 'Get' and the resource 'a single task by ID'. It distinguishes from sibling tools like runrunit_list_tasks (which returns multiple tasks) and runrunit_create/update/delete_task (which modify).

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. The description implies it's for retrieving a specific task by ID, but doesn't compare with runrunit_list_tasks or mention 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 are provided, so the description carries the full burden. It discloses that the tool copies files into ~/.cursor/skills, uses os.homedir, supports dry-run preview, and allows scoping to specific skills or project directories. Missing details on what happens on conflicts or error handling, but the core behaviors are 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 a few sentences long, front-loaded with the main action. It efficiently conveys usage and key options. Could be slightly more structured (e.g., bullet points), but it's clear and avoids verbosity.

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 (5 optional parameters, no output schema), the description covers the operation and parameter interactions well. However, it lacks information about return values (e.g., success message, counts) and potential side effects (e.g., overwriting existing files). This is a gap, lowering completeness to a 3.

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% (all 5 parameters have descriptions). The tool description adds contextual nuance: explaining the default for target ('global'), when project_root is needed, and that source_dir overrides auto-discovery. This goes beyond repeating schema information, so a 4 is warranted.

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 copies bundled Cursor skills to the user's Cursor skills directory, specifying the verb 'copies' and the resource. It distinguishes from sibling tools which are unrelated (comments, tasks, workflows, Discord, etc.), making the purpose 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 explicit use cases: 'onboard teammates or sync team SKILL.md workflows' and recommends 'Prefer dry_run:true first to preview.' It also explains parameter usage (dry_run, skill_names, target, project_root, source_dir). However, it does not explicitly state when not to use this tool 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?

No annotations provided, so description carries full burden. Clearly describes the operation as listing stages and returning id and name. As a simple read operation, it is transparent enough; could mention read-only nature but implied by 'list'.

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 fluff, front-loaded with the core action. Every word adds value. Ideal 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?

Simple tool with one parameter and no output schema. Description covers purpose, parameter usage, and integration with sibling tool. Lacks mention of error conditions or default behavior, but sufficient for its 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% with description for board_id. The description adds context by stating 'Use board_id from a task', reinforcing the schema's hint. Slightly exceeds baseline of 3 for full 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?

Clearly states verb 'List' and resource 'board stages', with examples of stages and explicit purpose to retrieve stages for moving tasks. Distinguishes itself by specifying usage with runrunit_move_task_stage.

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 context for when to use (get stages from task.board_id) and how to use the output (with runrunit_move_task_stage). Does not explicitly list when not to use or alternatives, but the guidance is clear and actionable.

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. It mentions optional filters but fails to disclose read-only nature, response format, pagination defaults, or any side effects. The behavior is implied but not explicitly stated.

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 with one clear sentence and a list of optional filters. It is front-loaded with the main action. However, it lacks a brief note on what the response contains, which would improve structure without adding much length.

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 output schema and 6 optional parameters, the description should explain default behavior (e.g., pagination default, what happens with no filters) and return value format. It fails to do so, making it incomplete for effective 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 baseline is 3. The description lists parameter names but adds no new meaning beyond what the schema already provides for each 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 'List all projects from Runrun.it' with a specific verb and resource. It distinguishes from sibling tools by focusing on projects, but does not explicitly differentiate from similar list tools like runrunit_list_tasks.

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 on when to use this tool versus alternatives. It does not mention prerequisites, when not to use, or any conditions for invocation.

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 must disclose behavioral traits. It fails to mention that the operation is read-only, any authentication needs, rate limits, or what the response includes. The name implies listing but lacks explicit 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 a single sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and 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?

For a simple list tool with one required parameter and no output schema, the description adequately states what it does. However, it does not describe the return format (e.g., 'returns a list of subtask objects'), which 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?

Schema description coverage is 100% (task_id with 'Parent task ID' description). The tool description adds no additional meaning beyond what the schema already provides, 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 states the tool lists subtasks of a task, using specific verb 'listing' and resource 'subtasks of a task'. This distinguishes it from sibling tools like runrunit_list_tasks which list tasks directly.

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 a clear context for use (listing subtasks) but does not specify when not to use it or mention alternatives among siblings. No exclusions or comparisons are given.

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 full burden but only states the basic function. It does not disclose any behavioral traits such as pagination, sorting, ordering, or side effects (e.g., whether it's read-only).

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 that fits the necessary information. It is concise without being overly short, though it could include slightly more detail without losing efficiency.

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 list tool with one required parameter and no output schema, the description is moderately complete. It does not mention that the output is an array of comments or provide any expected structure, but the simplicity somewhat mitigates this 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 coverage is 100% (one parameter with a basic description 'Task ID'). The description does not add any additional meaning beyond what the schema provides, resulting in a baseline score of 3.

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 'List' and the resource 'comments on a task' within 'Runrun.it'. It is specific and distinguishes this tool from siblings that get, create, update, or delete individual 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?

The description provides no guidance on when to use this tool versus alternatives like runrunit_get_comment for a specific comment or runrunit_create_comment for adding. No context on prerequisites or scenarios is given.

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, description should disclose behavior. It lists available filters for current user but lacks details on rate limits, auth, or whether it's read-only.

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 fluff. First states purpose, second provides usage guidance. 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 zero-param tool with no output schema, this description is fairly complete. Could specify output format but covers core purpose and usage.

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

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

No parameters exist, so schema coverage is 100%. Description adequately handles this by omitting param info. Baseline for 0 params is 4.

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 verb 'List', resource 'task filters', and scope 'available to the current user'. The use case for finding filter_id differentiates it from sibling list 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?

Explicitly identifies when to use: to find filter_id for specific filters. No alternative or exclusion, but sufficient for this tool.

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 mentions listing with optional filters but does not disclose pagination behavior (e.g., default page size, max limit), or how filters combine (AND vs OR). Adequate but not thorough.

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 concise sentence that front-loads the action and lists all filters. No wasted words; every element is informative.

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 14 optional parameters, no output schema, and no annotations, the description is incomplete. It does not explain return format, pagination defaults, or how filters interact. More context is needed for 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 coverage is 100%, so the schema already describes each parameter. The description lists parameter names but adds no new semantics beyond the schema. 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 states the tool lists tasks from Runrun.it and enumerates all optional filters, making its purpose distinct from sibling tools like runrunit_get_task (single task) or runrunit_list_projects.

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 when a single task is needed (get_task) or when subtasks are required (list_subtasks). It also lacks context on typical use 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?

No annotations provided, so description carries full burden. Discloses movement restrictions and a prerequisite. Lacks details on permissions, error handling, or rate limits, but sufficiently covers behavior for a move operation.

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 unnecessary words. Front-loaded with main action, then constraints and tips. Highly 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?

No output schema, but description covers purpose, usage guidelines, parameter semantics, and behavioral constraints. Complete for a simple move tool with no nested objects.

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 100%, baseline 3. Description adds value by explaining board_stage_name partial match and case-insensitivity, and linking board_stage_id to runrunit_list_board_stages. Doesn't clarify behavior if both params 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?

Clearly states the tool moves a task to a board stage (column). Specifies movement constraints (advance only, backward only to 'Task' or 'Blocked Task'), which distinguishes it from other task-related tools like runrunit_update_task.

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 explicit when-to-use and constraints: tasks must only advance, backward allowed only to specific stages. Also gives a prerequisite tip for stages requiring 'Link da branch', directing to runrunit_update_task.

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 discloses that the tool reads tags_data/tag_list, not repository files, and implies read-only behavior. Could state 'no side effects' explicitly but 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 sentences, no wasted words. Clearly front-loaded with purpose and examples.

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?

Low complexity with one parameter. Description covers purpose, data source, and output suggestion. Missing details on output format or error handling, but adequate for a simple detection tool.

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

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

Schema already has 100% coverage with parameter description. Tool description adds context: it suggests upload command and emphasizes tags as source, adding meaning beyond 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?

Description clearly states the tool identifies project platform based on task tags, listing examples. It is specific and distinguishes from sibling tools that handle comments, tasks, workflows, etc.

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?

Description explains when to use (when task tags define platform) and explicitly says it does not use repository files. However, no explicit when-not-to-use or alternative tool references.

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 must fully disclose behavior. It explains the tool suggests developers based on tasks and estimates, but omits details like how 'free queue' is calculated, whether it modifies data, or required permissions. This is adequate but lacks depth.

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 sentence that efficiently communicates the core action and context. No filler or redundant words; the sentence is well-structured and front-loaded with the main purpose.

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 lacks information about the output format (e.g., list of developers with ranking or details) and does not explain the computation logic. With no output schema, this gap significantly reduces completeness. Additionally, the complexity of 13 parameters is not addressed beyond 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 baseline is 3. The description adds minimal semantics beyond the schema, simply repeating the concept of filters. The parameter descriptions in the schema are already detailed (e.g., load_strategy, task_stage_ids), so the tool's description does not significantly enhance 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 tool's purpose: suggesting developers with the freest queue based on tasks in the Task column, considering estimates and optional filters. The verb 'suggests' and specific resource 'developers with freest queue' make it distinct from siblings, none of which offer similar suggestion functionality.

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 context for when to use the tool (when needing to suggest developers based on task queue), includes mention of optional filters, but does not explicitly state when not to use or provide alternatives. Given no sibling tool offers the same capability, this omission is acceptable.

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. It only says 'update' which implies mutation but does not disclose side effects, permissions, or constraints (e.g., can only update own comments, whether update is destructive).

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 with no wasted words. It is concise, though the brevity comes at the cost of missing behavioral guidance.

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 update tool with no output schema, the description is passable but lacks information on return values, error conditions, or prerequisites (e.g., comment must exist).

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 describes the two parameters (id and text). The description adds no additional meaning beyond what is in 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 'Update' and resource 'comment's text' and names the platform 'Runrun.it'. It clearly distinguishes this tool from siblings like create, delete, get, and reaction.

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 on when to use this tool versus alternatives. For example, it does not mention that this is for modifying existing comments, while creating or reacting are separate 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?

No annotations are provided, so the description carries full responsibility. It discloses the mapping of 'link_da_branch' to a custom field and explains that it expects a URL. While it doesn't detail all side effects (e.g., overwrite vs. merge), it gives enough behavioral context 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?

Two sentences with no redundancy. The first sentence states the purpose and required parameters; the second adds a crucial note about a special field and directs to a sibling tool. 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?

Given the parameter count (2, one nested), lack of output schema, and no annotations, the description covers the essentials: what the tool does, what fields can be updated (with examples), and how to handle a non-obvious custom field. It also addresses an ambiguous scenario (stage moves) by referencing the correct sibling tool.

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

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

Schema coverage is 100% (both parameters documented). The description adds value beyond the schema by explaining that 'link_da_branch' maps to custom field 'custom_32', providing an example URL, and clarifying that the task object should contain fields to update. This is more informative than the schema alone.

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 'Update a task on Runrun.it' with a specific verb and resource. It distinguishes from the sibling tool 'runrunit_move_task_stage' by explicitly mentioning that moving between columns should use that tool instead.

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 indicates when to use this tool (update task fields) and when not to (moving stages), naming the alternative tool. This provides clear guidance for an agent.

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 must carry the behavioral burden. It discloses that uploads go to Cloudinary and return a secure_url, and mentions env vars are already configured. However, it omits details about whether overwriting occurs, allowed image formats, error handling, or any destructive potential. The description is adequate but could be more 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 two sentences, perfectly front-loaded: first sentence defines purpose and output, second provides usage guidance. 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?

Given no output schema, the description hints at return value (secure_url). It covers the 2 parameters (1 required) with 100% schema coverage. It could mention file size limits or format restrictions, but for a straightforward upload tool it 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 coverage is 100%, so baseline is 3. The description adds useful context: for file_path it gives examples of absolute/relative paths and references browser_take_screenshot; for public_id it provides pattern examples. This enhances understanding beyond the schema alone.

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 uploads an image to Cloudinary and returns a public URL. It lists specific use cases (screenshots, evidence, PRs, comments), and no sibling tools perform similar uploads, so differentiation is clear.

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 tells when to use the tool (for screenshots, evidence, etc.) and mentions pre-configured environment variables. It does not state when not to use it, but there are no alternative upload tools among siblings, so it's clear.

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