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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states a key side effect: pausing the current task if the assignee is already working on another. It also discloses the staging requirement, giving agents important context beyond a simple 'start tracking' phrase.

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 efficient: two sentences, front-loaded with the action, followed by the side effect and the critical precondition. Every sentence earns its place with no filler or repetition.

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 action tool with no output schema, the description is complete. It explains what the tool does, the side effect, and the required board state, giving an agent everything necessary to decide and prepare for invoking it correctly.

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

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

Schema description coverage is 100%, so task_id and assignment_id are already documented. The description adds no parameter-specific detail beyond the schema, which meets the baseline but does not elevate it.

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-resource combination: 'Start tracking work on a task (play).' This unambiguously identifies the tool as a time-tracking/play action and distinguishes it from sibling tools like create, update, delete, or move operations.

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

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

The description provides a clear precondition: the task must be in the Ongoing column (board_stage_id: 96356) before calling. It implies when the tool should not be used, but it does not explicitly name an alternative tool like runrunit_move_task_stage for cases where the task is not already Ongoing.

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 carry the burden of behavioral disclosure, but it only states the primary action. It does not mention whether adding the same emoji twice creates duplicates or is idempotent, whether an existing reaction is replaced, or what happens if the comment does not exist.

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

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

A single, front-loaded sentence contains only the essential action and resource. No filler or repeated schema 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?

The tool is simple and the schema fully documents its two parameters, so the description is nearly sufficient. However, with no annotations and no output schema, it leaves open behavioral questions like idempotency and failure behavior, making it only minimally 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%, and both parameters already have clear descriptions (comment_id as number, emoji as character with example). The description adds no new semantic detail beyond the schema, so the baseline score of 3 applies.

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

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

Description uses a specific verb ('Add') and resource ('reaction...to a comment on Runrun.it'), making the operation unambiguous. It distinguishes this from sibling comment tools (get/create/update/delete_comment) by naming the emoji-reaction action.

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

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

No guidance is given about when to choose this tool over alternatives, such as updating a comment or creating a reaction via another endpoint. The context is implied only by the description and schema, with no explicit exclusions or preconditions.

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 exist, so the description must carry the burden. It discloses the plain-text requirement (no Markdown) and external visibility, which are meaningful behavioral constraints. It does not mention response format, permission requirements, or failure behavior for tasks without a guest channel, leaving some gaps.

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

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

Two short sentences, with purpose and usage front-loaded. Grammar is awkward ('For create a comment', 'use only text simple') and 'external/guest'/'external clients' is slightly redundant, but no sentence is wasted.

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 create operation with no output schema, the description covers purpose, channel scope, and text formatting constraint. It doesn't explain what happens if the task lacks a guest channel, but this is a relatively minor gap.

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

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

Schema descriptions are 100% for both parameters, so baseline is 3. The tool description adds the concrete constraint that text must be simple plain text without Markdown and clarifies that the comment targets the guest channel, going slightly 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?

States the verb 'create', resource 'comment', and scope 'external/guest channel' explicitly. This clearly distinguishes it from the sibling runrunit_create_comment by channel type, so an agent can tell them apart.

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?

Gives an explicit when-to-use condition: comments shared with external clients (channel_name: guest). It doesn't explicitly name runrunit_create_comment as the alternative for internal comments, but the channel qualifier makes the applicable context clear.

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 disclosure burden. It does this well by revealing non-obvious behaviors: default assignment to the caller, the fixed default board/column, and the description append semantics ('appended to any existing text, never replacing it outright'). It stops short of covering failure modes or permission requirements, but the key behavioral quirks an agent would trip on are disclosed.

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 key facts are front-loaded in the opening sentence (action, defaults, assignee), followed by requirements and optionals. It is reasonably compact, though the grammar is awkward ('assignee from who is call the tool') and the description-append clause partially duplicates the schema's own description 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?

For a 12-parameter create tool with no output schema and no annotations, the description covers the essentials — defaults, required params, key optionals — but leaves gaps. It doesn't hint at the return value (an agent will likely need the created task ID for subsequent calls like runrunit_get_task), and it doesn't clarify whether parameters like board_name/board_stage_name override the stated defaults.

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%, placing the baseline at 3. The description adds value beyond the schema with a concrete title format convention ('[project_name] - task_name') and by flagging which optional parameters matter most (description, project_id, assignments, desired_date). The trailing 'etc.' is vague, but the meaningful additions justify a step above baseline.

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

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

The description states a specific verb ('Create'), a concrete resource ('task on Runrun.it'), and precise default behavior: board Ongoing (ID: 96356), column Task, assignee = the caller. This clearly differentiates it from sibling tools like runrunit_update_task, runrunit_delete_task, and 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?

The description gives clear invocation context — default board, column, assignee, and which parameters are required vs optional — so an agent knows how to call it. However, it never explicitly states when to prefer this tool over alternatives (e.g., runrunit_update_task for modifications, runrunit_move_task_stage for stage changes) or when NOT to use it. Usage is implied by the name and defaults rather than spelled out.

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 burden of behavioral disclosure. It does disclose that creating a workflow 'starts tracking eligibility' and states prerequisite conditions. However, it does not describe the return value, failure modes, or whether any existing task state changes beyond workflow creation.

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 crisp sentences with no wasted words. The core action and its effect come first, followed by the eligibility restrictions. Every part serves a clear 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?

For a single-parameter create tool, the description covers the action, the effect, and the required preconditions. The absence of an output schema means return-value behavior is not explained, which is a minor gap, but the description is otherwise sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%: the only parameter, task_id, has a description 'Task ID'. The tool description adds contextual meaning by linking task_id to the eligibility constraints, but does not provide additional parameter-level detail beyond what the schema already includes.

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

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

The description states a specific verb and resource: 'Create a workflow for a task'. The parenthetical '(starts tracking eligibility)' adds a meaningful effect that helps distinguish this from generic create tools and from sibling tools like runrunit_create_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 gives explicit eligibility constraints: 'Task must not be closed, ongoing, or already have a workflow.' This clearly indicates when the tool can be used. It does not explicitly name alternative tools for other cases, but the constraints provide enough guidance for the agent to decide.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states only that a comment is deleted, but it does not say whether deletion is permanent, whether it cascades to related data, or whether special permissions are required. This is a meaningful gap for a destructive 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?

The description is a single, front-loaded sentence with no filler. For a tool with one required parameter, this is appropriately concise and every word earns its place.

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

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

For a low-complexity tool with one well-documented parameter, the description provides enough to understand the core operation and how to invoke it. However, because there is no output schema and no annotation coverage, it would be more complete if it mentioned permanence, error behavior, or access requirements.

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 covers 100% of parameters: id is a required number described as 'Comment ID'. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb and resource: deleting a comment on Runrun.it. This clearly distinguishes it from sibling comment tools like create_comment, update_comment, get_comment, and list_task_comments, because the action is explicit 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?

Usage is implied by the verb: use this tool when the desired outcome is to remove a comment. However, the description gives no explicit context, prerequisites, or contrast with alternatives, such as when updating a comment would be more appropriate than deleting 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?

With no annotations, the description needs to disclose whether deletion is permanent, whether it cascades to subtasks or comments, and any permission requirements. It only says 'Delete,' leaving the destructive implications and side effects unspecified.

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 single sentence is concise and contains no filler, but it is also underspecified for a destructive operation. It lacks any front-loaded caveats or contextual detail that would help an agent use the tool safely.

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 tool the schema covers the required id, so the description is minimally viable. However, absent annotations and output schema, useful context such as irreversibility and side effects is missing.

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%: the id parameter is described as 'Task ID' and marked required. The description adds no extra meaning about the parameter, so the baseline 3 applies.

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

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

The description states the verb 'Delete' and resource 'a task on Runrun.it,' so the basic purpose is clear. However, it is essentially a restatement of the tool name and adds no distinguishing detail beyond what the name already conveys.

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?

There is no guidance about when to use this tool, prerequisites, or alternatives. It neither explains when deletion is appropriate nor warns against using it when another task-related tool might be relevant.

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 disclosure burden and does real work: it reveals idempotency ('if not exists', 'avoid create duplicate channels'), name normalization ('Client 1' -> 'client-1'), and guild_id resolution via env fallback. The main gap is that it doesn't state what happens when the channel already exists (return existing vs error) or what the return value looks like.

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 tight sentences front-load the core function, then add normalization and configuration details. The only inefficiencies are minor redundancy with the schema's name-parameter description, which repeats the 'Client 1' -> 'client-1' example, and slight grammar friction ('avoid create duplicate channels').

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 the essentials: action, idempotency, naming pattern, and guild resolution. It is incomplete on the duplicate-channel outcome (no statement of return behavior), and it fails to clarify how this tool relates to the similarly-named runrunit_discord_get_or_create_channel sibling.

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 and the schema already documents all four parameters. The description adds no new parameter-level meaning: its normalization example ('Client 1' -> 'client-1') and the env-var fallback for guild_id both duplicate text already present in 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 states a specific verb and resource: 'Create a text channel in the Discord server (guild)', with the 'if not exists' qualifier conveying idempotent creation. It is clear about the core action. However, it does not differentiate itself from the sibling runrunit_discord_get_or_create_channel, which covers nearly the same behavior, so it stops short of a 5.

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

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

The description provides operational context: 'Use guild_id from env (DISCORD_GUILD_ID) or pass explicitly' and 'One channel per client pattern', which implies the intended use case. But it never names alternatives or exclusion conditions — notably runrunit_discord_get_or_create_channel and runrunit_discord_list_channels — leaving the when-to-use decision ambiguous.

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 behavioral burden and delivers: it discloses the naming convention (client_name slug transformation with a concrete example), the one-channel-per-client dedup rule, and the return value (channel_id, channel_name). It doesn't explicitly state what happens when the channel already exists, though 'Get or create' plus '1 channel per client' strongly implies idempotent return of the existing channel.

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 sentences, all earning their place, with purpose front-loaded. However, the first sentence is overloaded — the parenthetical crams in the dedup rule, the slug rule, and the example — and it contains a typo ('avaliable') that could confuse an agent. The information density is right but the packaging is rough.

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 return values, naming, and usage context reasonably well. The notable gap: the schema marks all 3 parameters optional, and the description calls client_name 'always avaliable' without clarifying what happens when zero arguments are supplied or which identifier takes precedence when both client_id and client_name are provided.

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 baseline is 3. The description adds meaningful operational value beyond the schema: it specifies that client_name must be slugified for the channel name and gives a concrete example ('Client 1' -> 'client-1'). This is essential since Discord channel names have strict format constraints and agents might otherwise pass the raw name.

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

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

The description states a specific operation ('Get or create a Discord text channel for a Runrun.it client') with a clear verb and resource. The one-channel-per-client constraint distinguishes it from the runrunit_discord_create_channel sibling, though not by explicit name. It is clear but stops short of fully differentiating from the create/list siblings.

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 context: 'Use before runrunit_discord_send_message to ensure the channel exists.' This routes the agent to the correct call ordering in a common workflow. However, it doesn't say when not to use it or when to prefer runrunit_discord_create_channel or runrunit_discord_list_channels instead.

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

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

The description discloses one meaningful behavior: the target guild is obtained from DISCORD_GUILD_ID or resolved from DISCORD_CHANNEL_ID. However, with no annotations present, the full burden falls on the description, and it does not mention that the operation is read-only, what the response contains, or failure behavior when env vars are missing.

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 short sentences with the main purpose first and the targeting detail second. There is no filler, and every sentence contributes useful 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 one-parameter tool with no output schema, this description is usable but slightly incomplete. It does not describe the returned channel data, such as whether channel IDs, names, or both are returned, which an agent may need when passing results to send_message or get_or_create_channel. With no annotations, there is also no safety context beyond the word 'list'.

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

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

The schema already documents guild_id as 'optional if env set', but the description adds extra value by explaining that DISCORD_CHANNEL_ID can be used to resolve the guild. This helps the agent decide whether to supply guild_id or rely on environment configuration.

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

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

The description uses a specific verb ('List') and a clear resource ('channels in the Discord server'), making the tool's purpose immediately obvious. It is also clearly distinct from sibling Discord tools like send_message, create_channel, and get_or_create_channel.

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 clearly frames when this tool is relevant: when channel enumeration from the configured Discord server is needed. It does not explicitly contrast with discord_get_or_create_channel or discord_send_message, but the read-only list intent is unambiguous enough for an agent to select it correctly.

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 behavioral burden and does disclose an auth dependency ('Requires BOT_RUNRUNIT_REPORT and channel_id'). However, it does not mention side effects beyond sending, failure modes, or response behavior, so coverage is adequate but not rich.

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

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

Two short sentences front-load the action and use cases, then state the requirements. Every sentence adds value and there is no redundant or vague wording.

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 4-parameter tool with no output schema, the description provides purpose, use cases, and required credentials. It does not explain return values or failure behavior, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description only repeats channel_id and adds no new parameter semantics beyond the schema.

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

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

The description states a specific action ('Send a message to a Discord channel') with a clear resource and intended use cases ('execution history or notifications'). This distinguishes it from sibling Discord channel-management tools like runrunit_discord_create_channel and runrunit_discord_list_channels.

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 explicitly says this tool is for sending messages for execution history or notifications, giving an agent clear context for when to select it. It does not name alternatives or state when not to use it, but the use-case framing is sufficient for this simple 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a safe read operation, but the description reveals nothing about the return shape, possible errors, permissions, or pagination behavior. It adds little beyond what the tool name already communicates.

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 concise sentence with no filler. The key information — operation, resource, lookup key, and platform — is all present and front-loaded.

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 single-ID getter with one required parameter, the description is sufficiently complete. No output schema exists, but the return value of a get-by-ID operation is self-evident. The lack of explicit safety annotations is mitigated by the read-only nature of the verb 'Get'.

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 single parameter 'id' is already described as 'Comment ID' in the schema. The description repeats the by-ID concept but adds no additional semantic detail, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Get'), a specific resource ('a single comment'), and a specific retrieval key ('by ID'), making it clearly distinct from sibling tools like runrunit_list_task_comments, runrunit_create_comment, and runrunit_update_comment. The scope is 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 implies usage when an agent already has a comment ID and needs that one comment, but it offers no explicit guidance about when to prefer list_task_comments or other comment-related tools. The usage context is inferable but not stated.

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?

With no annotations, the description carries the behavioral burden. It discloses that the operation returns stages with id and name, implying a read-only lookup, and provides no misleading side-effect information. For a simple list operation this is adequate, though it does not mention pagination or error behavior.

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

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

Two sentences deliver the core action, example output, parameter provenance, and a downstream-use note. Everything is front-loaded and every sentence earns its place with 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 one-parameter read-only list tool with no output schema, the description is complete: it names the action, the return shape, the source of the input, and the likely follow-up tool. An agent has enough context to call it correctly without additional fields.

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 only parameter, board_id, is already fully described in the schema as 'Board ID (from task.board_id)'. The description repeats this guidance ('Use board_id from a task') but adds little semantic value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific verb ('List'), a specific resource ('board stages'), and gives concrete examples of stages. It also clarifies that the tool returns stage id/name pairs, making it easy to distinguish from task-listing and task-mutation siblings.

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 states where to get the required board_id ('from a task') and explicitly connects the tool to runrunit_move_task_stage for moving tasks by stage name. It does not explicitly list alternatives or when not to use the tool, but the usage context is clear and sufficient for a single-purpose list 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 of behavior disclosure. It states a read-only listing operation and enumerates filters, which is transparent about scope. However, it does not disclose pagination defaults, whether filters are mutually exclusive, or what the response contains.

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

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

Two short sentences front-load the action and then list filters in compact form. There is no filler or redundant wording.

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 six optional parameters fully documented in the schema, the description supplies adequate contextual shorthand. It could mention response shape or default pagination behavior, but the low complexity and lack of an output schema keep this gap minor.

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

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

The schema already describes every parameter at 100% coverage. The description restates parameter names but adds no extra semantics beyond confirming they are optional.

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 opens with 'List all projects from Runrun.it', a concrete verb-resource pair that clearly identifies the operation. The 'projects' resource distinguishes it from sibling task-centric 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?

The description establishes a clear context: use this tool when the goal is to enumerate projects, and the optional filter list indicates how to narrow results. It does not explicitly name exclusions or compare with sibling list tools, but the resource distinction is sufficiently clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Listing' reasonably implies a read-only operation and makes the target resource clear, but the description does not address output shape, pagination, error cases, or any side effects. This is acceptable for a simple list tool but not rich.

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, direct sentence that leads with the intended action and names the object. Every word earns its place, and there is no redundancy or 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 one-parameter list operation with no output schema, the description plus the schema provide enough information to invoke the tool correctly. It could be more complete by explicitly stating the read-only nature or the response format, but nothing essential is missing for basic use.

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

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

The only parameter, task_id, is fully covered by the schema with the description 'Parent task ID'. The tool description adds no additional semantic detail, so the schema already handles the burden; a baseline score of 3 is appropriate.

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

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

The description states a specific action ('listing'), a concrete resource ('subtasks of a task'), and the platform ('Runrun.it'). It directly matches the tool name without merely repeating it and clearly differentiates it from siblings like runrunit_list_tasks and runrunit_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?

The phrase 'Use for listing subtasks of a task' establishes the intended scenario, which is helpful but generic. It does not mention alternatives, exclusions, or conditions for choosing this tool over a sibling, so an agent gets adequate but not explicit guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only says 'List all comments.' It does not state whether the operation is read-only, whether pagination or ordering applies, what permissions are required, or what the response shape looks like. The word 'List' implies a read operation, but that is not explicitly confirmed or elaborated.

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 with no filler or redundant wording. It front-loads the action ('List all comments') and the resource ('a task in Runrun.it'), making it efficient and easy to scan.

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 definition is minimal and lacks important behavioral context such as return format, pagination, read-only status, and differentiation from sibling comment tools. Since there are no annotations and no output schema, the description alone is not enough for an agent to understand the full behavior of the 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?

The only parameter, task_id, is fully described in the input schema as 'Task ID' with type number, so schema coverage is 100%. The description does not add any extra meaning about where the task_id comes from or how it is used, but because the schema already documents the parameter adequately, this is acceptable.

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 ('List all comments') on a clear resource ('a task in Runrun.it'), so the tool's primary purpose is immediately understandable. However, it does not explicitly differentiate itself from sibling comment tools like runrunit_get_comment or runrunit_create_comment, relying mostly on the tool name and the word 'all' for distinction.

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 about when to use this tool versus alternatives such as runrunit_get_comment for a single comment or runrunit_list_tasks for finding tasks. The description simply states what the tool does, leaving the agent to infer the appropriate use case without any exclusions, prerequisites, or routing hints.

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 behavioral burden. The word 'List' clearly indicates a non-mutating read operation, and 'available to the current user' conveys access scoping. It does not mention pagination or output shape, but these are less critical for a simple no-parameter list 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 short sentences with no filler: the first states the operation, the second explains the practical use case and includes a concrete example. 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 parameterless list tool with no output schema, the description gives essential context: what is listed, for whom, and how the result should be used. It is nearly complete; only minor details like return format or whether custom filters are included are left unspecified.

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

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

The tool accepts zero parameters, so there are no parameter semantics to document. The description adds value by explaining what to do with the result (find filter_id), which is sufficient at the baseline for a parameterless tool.

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

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

States a specific action ('List') and resource ('all task filters available to the current user'), clearly distinguishing it from sibling tools that operate on tasks, projects, comments, or stages. The mention of finding filter_id reinforces the tool's concrete purpose without ambiguity.

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 clear context by explaining the tool is used to find filter_id, including a concrete Portuguese filter example. It does not explicitly name alternatives or exclusions, but the use case is specific enough for an agent to select it appropriately 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 carries the full burden of behavioral disclosure. It only states the action and lists filters; it does not disclose pagination behavior, default limits, filter combinability, read-only nature, or any 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 a single front-loaded sentence, which is concise. However, the trailing list of filters adds no new information beyond the schema and is somewhat redundant, though not bloated.

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

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

With 14 optional parameters, no output schema, and no annotations, the description is too thin to fully support correct invocation. Missing are the response shape, pagination defaults, and whether filters combine; an agent would need to infer or probe.

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 only repeats parameter names already present in the schema and provides no additional meaning about formats, dependencies, or how filters interact.

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+resource ('List tasks from Runrun.it') with an explicit filter list, making its primary action clear. It is distinguishable from siblings like get_task, create_task, and list_subtasks, although it doesn't explicitly contrast itself with them.

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

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

No guidance is provided on when to use this tool versus get_task, list_subtasks, or other list tools. The phrase 'Optional filters' implies filtering capability but does not state contexts, exclusions, 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds meaningful context beyond the schema: stage-advancement rules and a required prerequisite field. It does not, however, describe what happens on failure or what the tool returns, which would be useful for a mutation without an output schema.

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

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

Three tight sentences: action, constraint, parameter guidance, and prerequisite. Every sentence earns its place and the most important info is front-loaded.

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 sufficient for a competent agent to invoke the tool correctly, including edge-case constraints and a prerequisite. The main gap is the absence of any mention of return values or failure behavior, especially since there is no output schema and no annotations to cover these.

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 value by clarifying that board_stage_name and board_stage_id are alternative ways to specify the destination, which is not obvious from the schema alone. It also ties the 'Link da branch' prerequisite to a separate tool.

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 ('Moves a task to a board stage (column)') with a clear resource and target. It is easily distinguishable from sibling tools like create_task, update_task, and list_board_stages.

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 explicit constraints on when moves are allowed ('Tasks must only advance; backward move is allowed only to Task or Blocked Task'), explains the two acceptable destination parameters, and names a prerequisite tool (runrunit_update_task) for stages requiring 'Link da branch'.

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 behavioral burden. It discloses that the tool does not infer platform from repository files, relies on tags_data/tag_list, and only 'suggests' a command rather than executing it. It does not detail failure modes or exact output, but the core behavior is 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?

Two sentences, with the main action and scoping condition front-loaded. Every clause adds value: the tag examples, the command-suggestion behavior, and the explicit exclusion of repository files.

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

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

For a one-parameter tool with no output schema, the description gives enough to invoke it correctly and understand the returned artifact (a suggested upload command). It omits edge cases such as unrecognized tag sets, but the scope is simple enough that this is a minor gap.

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

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

Schema coverage is 100%, with the task_id property already explaining that the task's tags define the platform. The description reinforces this but adds no new parameter-level detail, so it meets the baseline without going beyond it.

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 ('Identifies') and resource ('project platform'), and adds the exact mechanism: task tags in Runrun.it. It also mentions the secondary purpose ('suggests the command to upload the development environment') and explicitly differentiates from file-based detection, which distinguishes it from sibling task 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?

It clearly states the required context: platform detection is driven by task tags, so the agent should not attempt repository-file inspection. There is no explicit alternative tool named, but no sibling tool has the same detection role, and the description gives enough situational guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does explain the core logic (based on tasks in the Task column, estimates, and optional filters), but it doesn't mention whether the operation is read-only, what the return format is, or any edge-case behavior. Still, 'sugere' implies a non-mutating suggestion operation, adding some transparency beyond the tool name.

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 Portuguese sentence with no fluff or redundancy. It front-loads the main purpose and includes the key qualifiers (Task column, estimates, filters). It could be slightly better structured, but it earns its place and remains highly readable.

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 has 13 optional parameters and no output schema, the one-sentence description plus the rich parameter schema is mostly adequate for a simple call. However, it doesn't describe the return value (e.g., a list of developer IDs with queue scores), nor does it summarize which parameters are typically needed together for useful results. The schema covers individual parameter dependencies, so this is a partial gap rather than a critical one.

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

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

Schema description coverage is 100%, so all 13 parameters are already documented with meanings, defaults, and constraints. The description adds no additional parameter semantics beyond mentioning optional filters (time, projeto, tags), which are already covered in the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'sugere desenvolvedores com fila mais livre' based on tasks in the Task column with estimates and optional filters. This clearly distinguishes it from sibling tools like list_tasks or get_task, which focus on listing or retrieving tasks rather than suggesting developers by queue load.

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

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

The description implies the use case — finding developers with the freest workload — but does not explicitly say when to prefer this over alternatives or when not to use it. It doesn't name any sibling tools or provide exclusions, so the agent must infer the context from the description alone.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states that the mutation affects the comment's text, which is transparent about the primary effect. However, it does not disclose side effects, permission requirements, reversibility, or return behavior, leaving notable gaps for a write 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?

The description is a single, front-loaded sentence with no filler, efficiently conveying the core purpose. It is appropriately sized for a simple tool, though the brevity contributes to the missing usage and 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 two-parameter tool with full schema coverage, the description plus schema is enough to construct a basic call. However, there is no output schema, no annotations, and no guidance about the comment lifecycle or when to prefer sibling tools. It is minimally viable but not fully 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 input schema provides 100% coverage with descriptions for both parameters ('Comment ID' and 'New comment text'). The tool description adds no additional semantic meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Update') and a specific resource ('a comment's text') with a platform qualifier, making the tool's purpose unambiguous. It can be distinguished from sibling comment tools like create_comment, delete_comment, and comment_reaction without opening the schema, though it does not explicitly name alternatives.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention that it is for existing comments only, that create_comment should be used for new comments, or that delete_comment should be used for removal. The agent must infer usage solely from the tool name and general update semantics.

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.