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?

With no annotations provided, the description carries the full burden, and it discloses two non-obvious behaviors: Markdown is not accepted (plain text and raw URLs only), and the evidence-capture pipeline must run via the registrar-evidencias skill before this tool is invoked with the enriched text. It does not cover response or failure behavior, but the mutating trait is evident from the verb and the described workflow.

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 with the purpose front-loaded, the format constraint second, and the conditional workflow rendered as a compact numbered list. Every sentence earns its place, and nothing merely repeats what the input schema already states.

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 4-parameter create tool with no annotations and no output schema, the description covers purpose, formatting constraints, and the conditional evidence workflow thoroughly enough for correct invocation. The main gaps are minor: no return-value description and no explicit routing to the create_external_comment sibling when the comment should not be attached to a task.

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, but the description adds genuine meaning: it constrains the text parameter's format, and it specifies the exact enrichment format ('Antes: <url>' / 'Depois: <url>') and the step-by-step procedure for the url_antes/url_depois pair, going beyond the schema's brief 'append to text' note. It also clarifies that the enriched evidence block belongs in the text 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 states a specific verb (create), a resource (a comment on a task), and a platform scope (Runrun.it), which is immediately differentiable from the sibling comment tools (update_comment, delete_comment, list_task_comments, get_comment, create_external_comment). Even without naming an alternative, 'Create a comment on a task in Runrun.it' pinpoints the inline-comment creation role precisely.

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 operational context: a plain-text/raw-URL format constraint and an explicit conditional workflow for when url_antes and url_depois are both present, with numbered steps for the evidence pipeline. It stops short of a 5 because it never explicitly names alternatives or states when-not-to-use, but the conditions ('when both are provided') are unambiguous.

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 the behavioral disclosure burden. It explains that optional fields fill the template and that the tool returns the title format and body, but it does not disclose behavior for missing template files, path resolution failures, or whether any side effects occur. This 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?

The description is two sentences with no filler. The core behavior is front-loaded, followed by usage guidance and a concise list of the optional fields. Every sentence contributes value.

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

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

Given the tool's moderate complexity, full schema coverage, and lack of an output schema, the description explains what is returned and how optional parameters affect the template. It could mention error behavior or the exact output shape, but for a template-fetching tool the description is reasonably 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 description coverage is 100%, so the parameters are already well documented in the schema. The description adds a general statement that optional fields fill the template, but it does not need to repeat parameter details. 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 returns the pull request title format and body from a specific file, .github/PULL_REQUEST_TEMPLATE.md. It uses a specific verb ('Returns') and resource, and the purpose is immediately distinguishable from the sibling task-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?

The description gives explicit usage context: use before gh pr create or when opening PRs manually, so the description follows the project standard. It does not name alternative tools or exclusions, but given the sibling list contains no similar PR-template tools, this level of guidance is sufficient.

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 behavioral disclosure burden. It does add value by clarifying that the rich description is intentionally not included in this response. However, it does not describe the response shape, error behavior, or any access requirements, leaving relevant gaps for a tool with no annotations.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the note about the separate description endpoint is compact and immediately useful.

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 with one well-documented parameter and no output schema, this description plus the schema is largely complete. The only real omission is the exact return shape, which is a minor gap for such a straightforward operation.

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 has 100% coverage: the 'id' parameter is described as a Task ID with type number. The description adds no new parameter-level detail, but with full schema coverage there is little room or need to add more.

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 ('Get'), a specific resource ('a single task by ID'), and the system ('Runrun.it'). It also explicitly distinguishes itself from runrunit_get_task_description by noting that the rich description lives on a separate endpoint.

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 direction to use runrunit_get_task_description when the rich description is needed, which is a useful alternative. It does not discuss when to prefer list_tasks or other lookup tools, but for a single-task-by-ID operation the intended usage is clear enough.

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 does add behavioral context by calling out 'rich-text' and listing what the description may contain (requirements, acceptance criteria, links). However, it does not disclose output format, possible empty/null returns, or any read-only safety guarantee, though 'Get' strongly implies non-mutation.

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 fluff. The primary purpose is front-loaded, and the usage guidance directly follows. 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 simple one-parameter getter, the description gives enough context to use it correctly: what it returns, when to call it, and why. Minor omissions like exact rich-text format or error behavior are acceptable given the low complexity, but a fully complete description could have mentioned them.

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%, and the only parameter task_id is adequately described as 'Task ID' in the schema. The tool description adds no additional parameter-level meaning, 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 states a specific verb ('Get') and a specific resource ('rich-text description of a task'), and distinguishes it from the sibling runrunit_get_task by explaining that it loads fuller context. This makes the tool's purpose immediately 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 tells the agent when to use it: after runrunit_get_task and before starting work. It does not explicitly mention when not to use it, but the usage context is clear enough for a simple getter.

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. It discloses the write behavior (copies flat files preserving basename), the local-only scope, and the dry_run safety valve. However, it does not mention idempotency, overwrite behavior, or whether missing source/mcp package causes errors. Acceptable for the category 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?

Four sentences, front-loaded with the core purpose, then routing, then parameters. The Spanish phrase 'compartilhar/dividir com o time' adds minor noise but is understandable and does not hurt. Nearly all content 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 tool with 6 params, all covered in the schema, and no output schema, the description covers the critical behavior scope and safety valve. It does not mention whether the command returns a list of copied paths, but the lack of an output schema is offset by a clear behavioral summary. Slight gap around project-vs-global interplay, but target's schema description already explains that.

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 documents every parameter. The description adds useful shorthand (flat files, preserves basename including .agent.md) that clarifies target and agent_names behavior, but it does not deeply elaborate beyond what the schema provides. 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 opens with 'Local install only: copies agent markdown from mcp-runrunit (cursor-agents/) into ~/.cursor/agents', a specific verb and resource plus the destination scope. It also explicitly distinguishes itself from runrunit_share_cursor_agent for GitHub PR sharing, which separates it from the closest 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 when to use it ('Local install only'), recommends dry_run:true first, and explicitly says NOT for team sharing via GitHub and names the alternative (runrunit_share_cursor_agent). This is explicit when/when-not guidance with a named sibling.

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 and mostly delivers: it discloses the local-only scope, the copy destination, and recommends dry_run:true first, which signals a filesystem-write operation and a safety workflow. It stops short of describing overwrite/conflict behavior or the return format, but the dry_run guidance is meaningful behavioral context beyond a bare 'installs skills' statement.

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?

Dense and front-loaded: the core action and destination lead, exclusions and alternatives follow, and param hints close. The Portuguese parenthetical ('compartilhar / dividir com o time') is slightly unusual but serves a real disambiguation purpose for Portuguese-speaking users. 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 tool with 6 optional params, a nested categories object, no output schema, and no annotations, the description covers purpose, scope, when/when-not usage, alternative tools, param semantics, and a safety recommendation. The notable gaps are return-value expectations and file-overwrite behavior, but these are minor given how much context is already packed in.

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 genuine value beyond the schema by grouping parameters by role (skill_names, categories, target, project_root, source_dir), flagging them as optional, and connecting skill_names to the catalog discovery tool. The 'requires project_root when target is project' detail is already in the schema, so no double credit there, but the grouping and discovery hint justify 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 names a specific verb-resource pair ('copies bundled Cursor skills from mcp-runrunit into ~/.cursor/skills') and immediately differentiates itself from the sibling share tool. An agent can confidently distinguish this from runrunit_install_cursor_agents and runrunit_share_cursor_skill without inspecting either schema.

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

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

Explicitly states when to use ('when the user wants to sync skills onto their machine'), when NOT to use ('NOT for sharing via GitHub'), names the correct alternative (runrunit_share_cursor_skill), and gives a concrete discovery workflow (runrunit_list_cursor_catalog for ids). This is exemplary routing guidance.

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

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

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 provided, the description carries the behavioral burden. It discloses a meaningful side-effect boundary ('Does not copy files') and indicates a read-oriented discovery purpose. It could add more on return shape or error behavior, but for a simple listing tool this is solid.

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 wasted words: the main action, the filters, the intended usage, and the key side-effect caveat are all front-loaded and relevant.

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 will be discovered ('ids and descriptions'), which partially compensates for the missing output schema. Given the low complexity and fully documented optional parameters, the definition is nearly complete, though explicit return formatting is not described.

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 all five parameters are already documented with descriptions. The tool description only echoes the filter names (platform, technology, utility) without adding meaning beyond what the schema 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?

States a specific verb ('List'), exact resource ('bundled Cursor skills and agents from cursor-catalog.json'), and optional filters. It also distinguishes itself from install-style siblings by explicitly noting it does not copy files.

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 tells the agent when to use the tool: 'Use before install to discover ids and descriptions.' The 'Does not copy files' line provides a clear exclusion against using it for installation, though it does not name the install_* siblings as 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 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 present, the description carries the full behavioral burden and does so well. It discloses the main side effect (opens a pull request), the source directory (cursor-agents/), the auth requirement (GITHUB_TOKEN on the MCP server host only), auto-detection behavior, and the safety rule to never pass credentials. This gives an agent a strong picture of what will happen and what environment 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?

The description is front-loaded with the primary use case and then adds the distinguishing alternative, behavior, auth, and safeguards. Every sentence contributes essential information without becoming bloated, and the included language examples are compact and useful for matching user intent.

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 output schema and no annotations, the description covers the key invocation context: what it does, when to use it, where it reads from, and the required environment. It does not describe what the tool returns (e.g., a PR URL), but for the purpose of correct selection and invocation 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%, providing the baseline of 3. The description adds meaningful context beyond the schema by explaining that project_root is where git origin is auto-detected for owner/repo/base branch, and that env vars can override this. This helps an agent understand why the optional project_root parameter matters.

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 and resource: 'share a Cursor agent with the team through GitHub' and 'Opens a pull request with one markdown file from cursor-agents/'. It clearly distinguishes this tool from the local install sibling and the Bitbucket variants, so an agent can identify it 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?

It explicitly states when to use the tool ('Use when the user wants to share a Cursor agent with the team through GitHub') and names the alternative for the local-use case ('For copying agents into ~/.cursor/agents locally, use runrunit_install_cursor_agents instead'). The GitHub scope also implicitly routes away from the Bitbucket sibling, and the token and project_root constraints give clear 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 — and it delivers. It discloses the side effect (opens a PR), exact auth requirements (BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD on the MCP server host), auto-detection behavior (workspace, repo slug, base branch from git origin with env-var override), and a security rule ('Never pass credentials via this tool'). This is exemplary for an unannotated 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?

Four sentences, each earning its place: the usage trigger, the core PR behavior, the sibling alternative, and the auth/security constraints. The most decision-relevant information is front-loaded, and nothing is redundant with the schema.

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, trigger, alternative, auth, auto-detection, and parameter location comprehensively. The only gaps are the return value (e.g., PR URL) and error behavior if the agent file is absent from cursor-agents/, which are minor against all essential call information being present.

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 3 applies. The description adds context by tying agent_name to a markdown file under cursor-agents/ and confirming project_root is the git-origin detection point, but it does not add syntax or format details beyond what the schema already provides.

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

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

The description states a specific trigger ('share a Cursor agent with the team through Bitbucket'), a concrete mechanism ('Opens a pull request with one markdown file from cursor-agents/'), and includes Portuguese example phrasings to aid recognition. The Bitbucket-via-PR behavior clearly distinguishes it from the generic-runrunit_share_cursor_agent sibling, and it explicitly names the install tool it is not.

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?

An explicit 'Use when' condition is front-loaded, and the description names runrunit_install_cursor_agents as the alternative for the local-copy scenario. It does not explicitly contrast against runrunit_share_cursor_agent (the non-Bitbucket sharing sibling), though the Bitbucket channel and PR mechanism make most routing decisions obvious.

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 behavioral burden and discloses the key mutation facts: it 'Opens a pull request' in 'one atomic commit' covering the entire folder. It surfaces the auth requirement ('Requires GITHUB_TOKEN on MCP host') and the targeting logic ('repo identity and base branch auto-detected from project_root git origin (env overrides)'). It does not cover failure modes or the response shape, but the core side effects and prerequisites are visible.

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, each carrying distinct information: purpose and triggers, mechanism and scope, then exclusion and requirements. The multilingual trigger list is somewhat long but earns its place for intent routing, and the critical scoping constraint and exclusion are front-loaded before the less urgent details.

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 no annotations and no output schema, the description covers purpose, triggers, exclusions, mechanism, auth, and repo targeting. The main gap is the success response (e.g., PR URL/number) that an agent would need to report back to the user, since no output schema exists to fill that role.

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 both parameters are already documented and the baseline of 3 is met. The description adds meaning by defining what skill_name maps to — the 'cursor-skills/{skill_name}/ folder (SKILL.md, rules/, templates/, scripts/, etc.)' — and by explaining that project_root drives 'repo identity and base branch' detection, which the schema does not state.

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 opens with 'Primary tool when the user wants to share a Cursor skill with the team via GitHub' and specifies the exact mechanism: 'Opens a pull request that adds or updates the full cursor-skills/{skill_name}/ folder ... in one atomic commit.' It also names the sibling it is not ('Do not use runrunit_install_cursor_skills'), and the 'via GitHub' qualifier separates it from the Bitbucket variants in the sibling list.

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?

Explicit trigger phrases in both Portuguese and English ('compartilhar skill', 'dividir com o time', 'share skill with the team', 'open a PR for teammates') tell an agent exactly when this tool is the right call. It gives a direct exclusion with rationale: 'Do not use runrunit_install_cursor_skills for this — that only copies folders to local ~/.cursor/skills.' The 'via GitHub' framing implicitly routes GitHub users here versus the Bitbucket 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?

With no annotations provided, the description carries the full disclosure burden and handles it well: it reveals the external side effect (opens a shared-repo PR), the scoped write (adds/updates one folder in an atomic commit), the credential prerequisite (Bitbucket credentials on MCP host), and target resolution (repo and base branch auto-detected from project_root git origin with env overrides). It stops short of disclosing failure modes or what happens on existing branches/PRs.

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?

Front-loaded with the primary-use declaration, then mechanism, then exclusion and requirements — each sentence carries a distinct job. The multilingual trigger list lengthens the description, but the phrases are functional for cross-language intent matching rather than padding.

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 side-effecting tool with no annotations and no output schema, the description supplies the essential calling context: what the PR contains, what it requires (credentials), and how the target repo/branch is chosen. Missing details like the return shape (PR URL) and behavior when no git remote exists are the only 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 description coverage is 100%, so the schema already documents both parameters; baseline 3 applies. The description adds marginal value by tying skill_name to the physical folder cursor-skills/{skill_name}/ and clarifying that project_root feeds the git-origin detection of repo identity and base branch.

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

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

States a specific verb+resource+mechanism: sharing a Cursor skill via Bitbucket by 'opens a pull request that adds or updates the full cursor-skills/{skill_name}/ folder'. Multilingual trigger phrases (Portuguese and English) sharpen intent matching, and naming the folder scope (SKILL.md, rules/, templates/, scripts/) differentiates it from the agent-sharing 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?

Explicitly declares itself the 'Primary tool' for the Bitbucket sharing use case and gives a direct when-not rule: 'Do not use runrunit_install_cursor_skills for this — that only copies folders to local ~/.cursor/skills.' The exclusion names the exact sibling most likely to be confused and states the reason. Only minor gap: it does not contrast with runrunit_share_cursor_skill (non-Bitbucket path), but the via-Bitbucket condition already routes that decision.

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?

Annotations are absent, so the description carries full responsibility for behavioral disclosure. It explains custom field storage but does not state whether the update is partial/merge or full replacement, what happens to omitted fields, required permissions, or what the response contains. These are important gaps for a mutation tool.

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

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

The description is compact and front-loaded with the core action, then covers special-case parameters, then routes to a sibling tool. A small amount of redundancy with the schema's custom-field mapping exists, but the extra explanations earn their 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 an update tool with no annotations and no output schema, the description covers main usage well and resolves the tricky PR/branch-link parameter choice. However, it does not explain merge semantics, whether additionalProperties keys are accepted, error behavior, or return values, so it is 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?

Schema coverage is 100%, so the schema already documents all parameters and their descriptions. The description adds value by giving usage examples, clarifying the distinction between the two branch-link parameters, and explaining that link_da_branch_relatorio is for task reports.

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 opens with a specific verb and resource: 'Update a task on Runrun.it.' It clearly states the required inputs (task ID and fields object) and gives concrete examples. It also distinguishes itself from the sibling runrunit_move_task_stage by explicitly delegating column moves to that tool.

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 tells the agent exactly when to use link_da_branch vs link_da_branch_relatorio, including the context of task reports. It also explicitly redirects column moves to runrunit_move_task_stage, preventing misuse of update_task for stage changes.

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