retro

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

The readOnlyHint annotation already indicates a safe read operation, and the description adds valuable context about the exact data returned (estimation scale, progress, current task, join link). It is consistent with the annotation and gives the agent a clear expectation of the response content.

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

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

Two concise sentences with front-loaded purpose. The first sentence immediately states what the tool does, and the second sentence succinctly redirects to a sibling tool. No filler or redundancy.

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

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

For a simple read tool with one parameter and no output schema, the description covers the return content well and mentions the related sibling tool. It could mention when to use this tool (e.g., needing a single game's overview) but the 'one' keyword implies that. Overall, it is complete enough for an agent to invoke correctly.

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

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

The schema has 100% coverage for the single parameter game_id with a basic description. The description does not add further semantic detail about the parameter beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns one planning poker game' with a specific list of included fields. It distinguishes itself from siblings like poker.games.list by emphasizing 'one' game and from poker.game.tasks.list by explicitly noting the difference.

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 usage guidance: 'Use poker.game.tasks.list for the tasks themselves.' This tells the agent when not to use this tool, helping avoid confusion with the sibling tool that returns task details.

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 empty annotations, the description carries the full burden. It discloses the required mcp:write scope and the fact that the tool returns a join link, which are important behavioral traits. It does not go into error handling or side effects, but for a simple create operation this is a solid disclosure.

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

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

The description is only two sentences long. It front-loads the primary action and return value, then succinctly covers the scale choice and scope requirement. Every sentence earns its place, with no wasted words.

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

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

For a 4-parameter creation tool with no output schema, the description covers the core purpose, the key output (join link), the scale presets vs custom values, and the authorization scope. It leaves out details like team_id requirements, but those are adequately explained in the schema, so the overall context is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a note about ready-made scales and passing custom scale_values, but this largely echoes the schema's existing parameter descriptions. No significant new meaning is added beyond what the schema already provides.

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

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

The description clearly states 'Creates a planning poker game for a team and returns the link participants join with,' which uses a specific verb (creates) and resource (planning poker game). This distinguishes it from sibling tools like poker.games.list and poker.game.get, which are clearly different 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 clearly indicates when to use the tool: when creating a new planning poker game. It also provides useful guidance on choosing between ready-made scales and custom scale_values. However, it does not explicitly mention alternatives or when not to use this tool, so it misses the top tier.

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 adds useful behavioral details beyond the readOnlyHint annotation: ordering (newest first), inclusion of task/estimate counts, and exclusion of personal games. This gives the agent a clear picture of what to expect without contradicting 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 sentences, front-loaded with the core purpose, and every clause conveys meaningful information without redundancy. No fluff 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 list tool with no output schema, the description covers the essential aspects: what is returned, the ordering, and a key limitation (personal games not exposed). It could detail return object fields, but this is reasonable for the tool's simplicity.

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

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

Schema coverage is 100% and the parameters are well-described in the schema (limit with default/max, team_id with condition). The description does not add any extra meaning beyond the schema, so the 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 planning poker games for a team, with ordering (newest first) and specific data content (task counts and estimates). This effectively distinguishes it from siblings like poker.game.get (single game) and poker.games.create (creation).

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

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

It specifies when team_id is required (more than one team available) and instructs to call retro.teams.list first, providing a direct prerequisite. It doesn't explicitly exclude alternatives, but the context is clear enough for selection.

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

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

With empty annotations, the description carries full responsibility. It discloses side effects: hiding clears votes and drops the estimate, and permission requirements: 'Requires mcp:write scope'. It also reveals that the estimate is computed from votes, not set directly.

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 three sentences, each conveying essential information: main function, alternative behavior, and permissions. No superfluous words.

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

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

The description covers the tool's purpose, side effects, permissions, and the reveal=false mode. Since there's no output schema, it could mention the return value, but the phrase 'computes its estimate' implies the result. Overall, it's complete for a straightforward 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 schema already has descriptions for all parameters (100% coverage). The description adds context that the reveal flag controls both revealing and hiding, but this is already in the schema. No additional parameter meaning is added beyond the schema, so baseline 3.

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

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

The description clearly states the tool's function: 'Reveals the cards of a task and computes its estimate from the votes cast'. It also distinguishes itself by noting 'this is the only way an estimate appears, there is no way to set a number directly', which differentiates it from sibling tools.

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

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

The description provides explicit when-to-use guidance: if you need to produce an estimate, this is the only way. It also explains the reveal=false behavior for re-votes, and states the prerequisite 'Only the team owner can change a game'.

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 empty, so the description carries full burden. It discloses the required 'mcp:write scope' permission and clarifies the manual nature ('by hand') versus import. It does not describe return behavior or error handling, but the scope requirement and manual approach are meaningful behavioral context.

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

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

Two sentences with no wasted words. The first sentence states purpose and usage context, the second names the alternative and required scope. Well-structured 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?

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description covers purpose, usage context, alternative, and permission requirement. It lacks return format details but that is not critical here. The description is complete enough for an agent to select and 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 description coverage is 100%: both game_id and tasks have descriptions. The description adds no additional parameter-level detail beyond the schema, and with full coverage, 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 clearly states 'Adds tasks to a poker game by hand' with a specific verb and resource. It also distinguishes itself from the sibling tool poker.game.tasks.import by explicitly mentioning the alternative for pulling tasks from Jira or Linear.

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 use case: 'for work that lives outside an issue tracker, or when no tracker is connected.' It also gives a direct alternative: 'To pull tasks from Jira or Linear use poker.game.tasks.import instead.' This fully covers when to use versus alternatives.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the action changes what everyone sees, is restricted to the team owner, and needs mcp:write scope. It does not mention failure modes or side effects beyond the current selection, but these are reasonable for a simple selection 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 three short sentences that are front-loaded with the primary action, followed by the permission constraint and write scope. Every sentence adds meaningful information with no 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 simple two-parameter mutation tool with no output schema, the description sufficiently covers the action, effect, permission, and scope. It does not explain success response or error conditions, but these are not required given the simplicity and existing schema hints.

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 no extra parameter semantics; the schema already provides descriptions for both game_id and task_id, with task_id referencing poker.game.tasks.list.

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 ('puts') and clearly identifies the resource and effect: the selected task becomes the one being estimated and is visible to everyone. This distinguishes it from sibling tools like task.reveal (revealing estimates) and tasks.add (adding a new 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 includes authorization constraints ('Only the team owner can change a game' and 'Requires mcp:write scope') but does not explicitly state when to use this tool versus alternatives such as task.reveal or tasks.add. The use case is implied but not contrasted with 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 empty annotations, the description discloses key behavioral traits: skipping existing tasks ('Tasks already in the game are skipped'), authorization requirements ('Only the team owner can change a game'), and security scope ('Requires mcp:write scope'). It does not contradict 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?

Four sentences, front-loaded with the primary purpose, followed by usage modes, behavior, and permissions. Every sentence adds value without redundancy.

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

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

Covers purpose, usage modes, permission prerequisites, and idempotency behavior. It could mention what happens when both iteration_ref and query are provided or error handling, but overall it is a strong description for a moderately complex 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?

Though schema coverage is 100%, the description adds the mutual exclusivity relationship between iteration_ref and query, and links iteration_ref to poker.iterations.list, providing extra semantic context 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 verb ('Pulls') and resource ('tasks from a connected issue tracker into a poker game'), clearly distinguishing from sibling tools like poker.game.tasks.add by emphasizing the external tracker source.

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 indicates when to use it (to import a whole sprint via iteration_ref or search by query) but does not explicitly name alternatives or exclusion rules. The instruction 'Give it either iteration_ref ... or query' provides clear context for invocation.

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

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

Annotations declare readOnlyHint=true, and the description adds contextual behavior beyond that: it reveals the returned fields, explains the meaning of needs_sync, and clarifies the estimated filter semantics. This gives the agent a clear model of what the tool returns and how to interpret it.

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 earns its place: the first describes the return payload, the second explains needs_sync and a downstream action, and the third explains filtering. 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 list tool with no output schema, the description sufficiently covers what is returned, how to interpret the special field, and how to filter. It also connects to a sibling tool, making the chain of operations clear.

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

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

The input schema already covers all parameters thoroughly (100% coverage). The description adds a useful conceptual mapping of estimated to 'done or left', which helps the agent reason about the parameter's purpose without repeating schema details.

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 tasks of a poker game and specifies the exact fields (estimate, individual votes, tracker key, link). It also distinguishes the tool's output from the sync tool by explaining how needs_sync feeds into poker.game.task.sync.

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 guidance on when to use the output: tasks with needs_sync should be fed to poker.game.task.sync. It also explains how to use the estimated filter to narrow results to done or remaining tasks, making alternatives and follow-up actions 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, the description carries the full burden. It discloses that this is a write operation, requires the mcp:write scope, and is restricted by ownership and integration permissions. However, it does not describe side effects like whether the write is idempotent, reversible, or what happens on conflict, leaving some behavioral ambiguity.

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 short sentences, no filler. The first sentence immediately states the purpose; the second and third provide essential constraints. 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?

This is a mutation tool with no annotations and no output schema. While the description covers prerequisites, permissions, and parameter hints, it does not state what happens on success (e.g., returns updated task, returns nothing) or failure. Given the moderate complexity of a two-parameter sync action, this leaves a notable gap for the agent to infer behavior.

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 extra semantic value by explaining that task_id should refer to tasks with needs_sync (pointing to poker.game.tasks.list) and that game_id must belong to an imported game. This goes beyond the raw schema.

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

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

The description clearly states the tool writes the estimate back to an issue tracker, with concrete examples (Jira story points, Linear estimate). This is a specific verb+resource and is distinct from all sibling tools (no other sync tool exists).

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

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

The description provides explicit prerequisites and exclusions: it only works for imported tasks, only when the integration has write permissions, and only the team owner can use it. It also directs the agent to poker.sources.list to verify permissions, giving clear context for when to invoke. The only missing element is an explicit alternative tool, but no alternative sync tool exists.

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?

Beyond the readOnlyHint annotation, the description discloses that only active and upcoming iterations are returned, that terminology may differ for future trackers, and that Linear returns an empty list. This provides useful behavioral context beyond the annotation, though it does not specify response shape or ordering.

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 three sentences, each serving a distinct purpose: defining the resource, explaining filtering and integration, and noting the Linear edge case. There is no redundant or filler 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 simple read-only listing tool with no output schema, the description covers what is returned, how to filter, how results connect to another tool, and the main edge case. It could be more explicit about the exact structure of the returned iteration objects, but it does mention 'ref' and gives enough context for practical use.

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

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

The input schema already documents all three parameters with descriptions, including the query filter example. The description adds the cross-tool note about passing the iteration ref to poker.game.tasks.import, but this relates more to output usage than to parameter semantics. Therefore, the description does not significantly enrich parameter-level meaning beyond the schema.

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

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

The description uses a specific verb ('Returns') and names the exact resource ('iterations of a connected issue tracker'), with concrete examples such as Jira sprints and a clear distinction from sibling tools like poker.sources.list. It also specifies that only active and upcoming iterations are returned.

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

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

The description explicitly explains how to use the query parameter for filtering, tells the user to pass the iteration ref to poker.game.tasks.import, and provides an explicit alternative for Linear (search by text) since it returns an empty list. This is clear when-to-use and when-not-to-use 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?

The readOnlyHint annotation is complemented by additional context: the tool reveals connection-dependent behavior and the meaning of an empty result. This goes beyond the annotation by explaining the semantic impact of the output, which is valuable for the agent.

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 front-load the core purpose and include both usage dependency and edge-case interpretation. No filler or redundancy—every word contributes to understanding.

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?

Without an output schema, the description fully covers what the tool returns (trackers and their capabilities), when to call it, and how to interpret an empty list. This is sufficient for an agent to invoke correctly and understand outcomes.

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 (team_id) is fully documented in the schema with 100% coverage, including guidance to call retro.teams.list first when multiple teams exist. The description adds no extra parameter semantics, 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 clearly states 'Returns the issue trackers connected to a team' and specifies what each tracker can do (search, list iterations, write estimates). It distinguishes itself from sibling poker tools by positioning as the first call that other tools depend on, making its purpose unambiguous.

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

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

Explicitly instructs 'Call this first — the other poker tools depend on what is connected,' providing definitive when-to-use guidance. It also gives an edge-case directive: an empty list means tasks must be added manually via poker.game.tasks.add, covering exclusions.

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

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

With no annotations, the description carries the full burden. It discloses the 'mcp:write scope' requirement, which is valuable. However, it does not mention idempotency, side effects beyond marking completed, or response 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 concise sentences, front-loaded with the core action. No wasted words.

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

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

For a simple single-parameter tool, the description gives the essential purpose and scope. However, it lacks details about return values or behavior when the item is already completed, which would be helpful given no output schema or annotations.

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

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

The input schema fully documents the single parameter with a clear description. The tool description adds no additional parameter semantics 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 clearly states the tool's function with a specific verb and resource: 'Marks an action item as completed.' It is distinct from siblings like retro.actions.update, but does not explicitly differentiate between 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?

The description provides no guidance on when to use this tool versus alternatives like retro.actions.update. It only mentions the required scope, which is a prerequisite, not usage context.

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

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

Annotations are empty, so the description is the only behavioral disclosure. It adds the auth requirement 'Requires mcp:write scope' but doesn't describe return values, side effects, or failure modes. This is a minimal but non-empty disclosure.

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

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

One concise sentence that states both operation and required scope. Every word earns its place; no redundant qualifiers.

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 schema handles parameter definitions, and the description states the essential operation, but the absence of an output schema and any mention of return behavior leaves a gap. For a simple create tool, the description is adequate 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?

Input schema covers all 5 parameters with inline descriptions (100% coverage). The description adds no 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 uses the specific verb 'Creates' with a clear resource ('new action item on a retrospective board'), immediately distinguishing it from sibling tools like update/list/complete. No ambiguity about the operation.

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 implies use for creating action items, but doesn't explicitly contrast with retro.actions.update or retro.actions.complete. The 'Requires mcp:write scope' is a permission prerequisite, not tool-selection 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?

The readOnlyHint annotation already covers the safety profile, and the description adds valuable behavioral context: it covers every team by default unless team_id narrows it, and filters by status, assignee, and date. This goes beyond the schema, which only describes individual parameters.

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

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

The description is concise, front-loaded with the core purpose, and every sentence earns its place. It avoids restating the schema and includes only high-value context like scope and the alternative tool.

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 read-only list tool with no output schema, the description is complete: it explains the cross-retrospective scope, default team behavior, available filters, and directs to the board-specific alternative. No critical context 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%, so the schema fully documents all five parameters with types and defaults. The description adds minimal extra meaning beyond mapping filters to concepts like status, assignee, and date, but it does not introduce new syntax or format details.

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 action items across all retrospectives at once, distinguishing it from the sibling tool retro.board.actions.list which works on a single board. The verb 'Returns' and the resource 'action items across all retrospectives' are specific 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?

Explicitly explains when to use this tool: to get actions across all boards instead of walking them one by one with retro.board.actions.list. It also mentions filtering by status, assignee, and date, giving clear context for usage.

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

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

The description discloses the mutation behavior and the required write scope, adding useful safety context beyond the empty annotations. It does not detail side effects, partial update semantics, or return values, but the auth requirement helps.

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 one sentence with clear front-loading of the purpose, followed by the auth requirement. Every word adds value, and there is no redundancy.

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

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

For a simple update tool with five well-documented parameters and a single required ID, the description plus schema covers the essential aspects. It notes the required scope and updatable fields, though it does not describe the return value; given no output schema, 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?

The input schema already provides 100% coverage with detailed descriptions for all five parameters, including guidance for assign_to. The tool description only repeats field names without adding new semantic detail, so it meets the baseline of 3.

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

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

The description clearly states 'Updates an existing action item' with a specific verb and resource, and enumerates the mutable fields (text, priority, due date, assignee), distinguishing it from sibling tools like create, complete, and 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?

It provides clear context ('existing action item') and a prerequisite ('Requires mcp:write scope'), which tells the agent when it is appropriate to call. However, it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds the returned fields, which is useful, but it does not disclose other behaviors like default filtering (include_completed defaults to false), pagination, or error handling. It adds some value but leaves gaps.

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

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

The description is a single, clear sentence that front-loads the core action ('Returns action items...') and uses no unnecessary words. It is concise and well-structured.

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

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

For a simple read-only list tool with complete schema coverage and readOnlyHint annotations, the description provides adequate context by listing key output fields. However, it does not mention the include_completed default or differentiate from the similar retro.actions.list sibling, 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 description coverage is 100%, with both board_id and include_completed fully described. The description does not add any additional parameter semantics beyond what the schema already provides, 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 clearly states the tool 'Returns action items from a retrospective board', using a specific verb and resource with board-scoping that distinguishes it from sibling tools like retro.actions.list. It also lists key returned fields (status, priority, assignee, due date), making the purpose unambiguous.

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

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

The description implies usage for board-specific action items but provides no explicit guidance on when to use this tool versus alternatives such as retro.actions.list or retro.actions.create. No exclusions or alternative recommendations are given, so the agent gets only implied context.

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

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

With readOnlyHint=true in annotations, the safety profile is already disclosed. The description adds valuable behavior context by stating that health_check returns null when no health check exists, and it clarifies the nature of the data (e.g., 0-10 scale, same score across previous retrospectives). No contradiction with 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 sentences with front-loaded purpose ('Returns the health check'), followed by a precise list of contents and a clarifying null case. Every sentence earns its place; no redundancy or fluff.

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 read-only tool with one parameter, the description fully covers what the tool returns (scores, alignment, turnout, previous data) and handles the null edge case. No output schema exists, but the description compensates by specifying the output contents. Complete 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% for the single parameter board_id, and the schema already describes it as the board ID. The description does not add further parameter-level meaning beyond what the schema provides, so a 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 uses specific language ('Returns the health check of a retrospective') and enumerates distinct elements (score per category, alignment, turnout, previous scores). This clearly differentiates it from sibling tools like retro.board.summary.get and retro.board.roti.get.

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 when to use the tool by stating exactly what data it returns, but it does not explicitly mention alternatives, exclusions, or conditions beyond the null case. No guidance on choosing between this and other board tools is provided, so usage context is implied rather than explicit.

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

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

Annotations declare readOnlyHint=true, so the safe-read nature is already covered. Description adds context about returned content (clusters, sentiment, urgency, category) but does not disclose any additional behavioral traits such as latency, staleness, or permission requirements.

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

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

Single sentence, front-loaded with action and resource, no filler or redundancy. Efficiently communicates the core 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 simple one-parameter read tool with annotations and schema coverage, the description is largely complete. It explains the two main return categories (insights and suggested actions) and insight content, though it omits output structure details.

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 covers board_id with a 100% description, so baseline 3 applies. Description adds no extra parameter semantics 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?

Description uses specific verb 'Returns' and identifies a unique resource: insights (clusters) and suggested actions for a retrospective board. It distinguishes from siblings by listing specific content dimensions (topic clusters, sentiment, urgency, category analysis).

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

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

No guidance on when to use this tool versus sibling tools like retro.board.summary.get, retro.board.health.get, or retro.board.actions.list. No exclusions, prerequisites, or alternative recommendations are provided.

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 burden of disclosing behavioral traits. It explicitly states the permission requirements for deleting messages beyond one's own, which is important behavioral context for a destructive action. The destructive nature is evident from the verb 'deletes', so while it doesn't mention irreversibility, the added access policy nuance pushes it above a baseline 3.

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 wasted words. The first sentence states the core purpose, and the second clarifies access policies. It is well-structured 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?

Given the simplicity of the tool (one parameter, no output schema, no annotations), the description covers the essential aspects: what it does and who can use it under what conditions. It is complete enough for a straightforward delete operation, though it could arguably mention that deletion is permanent, but the verb 'deletes' implies this.

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

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

The input schema already provides 100% coverage for the only parameter, message_id, with a clear description ('The ID of the message to delete'). The tool description does not add any additional meaning about the parameter, so it meets the baseline for high schema coverage.

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

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

The description clearly states the action: 'Deletes a single board message.' This is a specific verb (deletes) plus resource (board message), and it distinguishes this tool from sibling tools like retro.board.messages.list and retro.board.messages.update, as it is the only message deletion 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 provides clear context on when the tool can be used by explaining the access policy: users can delete their own messages, or any message with board update rights (requiring mcp:write scope). It does not explicitly mention when not to use it or alternatives, but the permission context is valuable.

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 readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral context beyond that by specifying the return structure ('organized by template columns') and included fields (text, sentiment, category, grouping, vote counts). It does not mention pagination or access requirements, but for a read-only list tool this is acceptable.

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

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

The description is two sentences, front-loads the primary purpose, and includes only relevant details about organization and return fields. Every sentence earns its place with 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?

The tool is simple (single parameter), has a read-only annotation, and the description adequately covers return content and organization despite the lack of an output schema. It is complete enough for an agent to select and 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 description coverage is 100%, with board_id already described as 'The ID of the board to get messages for.' The description adds no additional meaning about the parameter, 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 uses a specific verb ('Returns') and identifies the exact resource ('participant messages (cards) for a retrospective board') with added detail on organization ('by template columns'). This clearly distinguishes it from sibling tools like retro.board.messages.update/delete_own which mutate messages rather than list 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?

The description implies usage: use this tool to fetch all participant messages for a board. However, it does not explicitly state when to prefer it over alternatives (e.g., retro.board.summary.get) or provide exclusion criteria. The context is clear but not prescriptive.

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

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

With no annotations provided, the description carries the full burden. It discloses the action (update text) and the ownership requirement, but does not mention error behavior (e.g., what happens if the message doesn't exist or the user is not the creator), return values, or confirm whether the update is partial/full. This is basic transparency but lacks important behavioral context.

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

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

The description is a single sentence, front-loaded with the action and resource. It includes the key constraint without any filler or redundancy, making it highly concise and easily scannable.

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 that this is a simple two-parameter update tool with no output schema and no annotations, the description is reasonably complete. It explains the core operation and the ownership restriction. Missing details about error handling or success responses are minor given the tool's simplicity, so it does not feel incomplete.

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: both 'message_id' and 'text' have descriptions. The tool description adds no additional meaning beyond what the schema already states, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb (updates) and resource (board message) and adds a critical scope constraint ('created by the current MCP user'), which distinguishes it from siblings like retro.board.messages.list and retro.board.messages.delete_own. It clearly states what the tool does and for whom.

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 implies when to use this tool: when you need to update the text of an existing board message and you are the creator. It does not explicitly mention alternatives or exclusions, but the ownership constraint serves as effective contextual guidance. Sibling tools like delete_own handle separate operations, so the usage context is 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?

The annotation readOnlyHint=true already signals a safe read operation, lowering the burden on the description. The description adds value by specifying what is returned (average score, distribution, trend across previous retrospectives), which is behavioral context beyond the annotation. It does not address edge cases like empty boards or data freshness, but that is acceptable for this simple getter.

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

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

The description is a single sentence that is concise and front-loaded with the action and resource. It includes no filler or redundant information, making every word contribute to understanding the tool's purpose and output.

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 one well-documented parameter and an annotation confirming read-only, the description covers the tool's purpose and the nature of its return values. It does not specify an output schema (none exists) or error conditions, but for a simple read tool, this is sufficiently complete to guide correct usage.

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

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

The schema provides 100% description coverage for the single parameter board_id, so the description does not need to add extra parameter details. The description adds no new semantics beyond the schema, but the schema itself already clearly explains that board_id is the board identifier. This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('ROTI voting metrics for a retrospective board'). It also enumerates the contents (average score, distribution, trend), which distinguishes it from sibling tools like retro.board.health.get or retro.board.summary.get.

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 this is the tool for ROTI metrics but does not explicitly state when to use it over alternatives or mention any exclusions. Given there are sibling tools for board health, summary, and insights, explicit guidance would be helpful, but the unique metric name makes the purpose reasonably 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?

Beyond the readOnlyHint annotation, the description discloses sorting order ('newest first'), default inclusion of unfinished boards, the meaning of finished_only, and the is_finished flag in responses. It also clarifies team_id requirements, adding behavioral context.

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

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

Three sentences, with the core purpose in the first sentence. Each sentence provides distinct useful information without redundancy.

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

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

Covers ordering, filtering, unfinished board behavior, and team_id condition. It also hints at the response containing is_finished. Though there's no output schema, the description does a good job for a list 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?

All four parameters are documented in the schema (100% coverage). The description adds a small insight about team_id being conditional ('with a single team it can be omitted'), but largely relies on the schema's existing descriptions.

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

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

The description clearly states 'Returns retrospectives (boards) of a team, newest first', which specifies both the resource and ordering. It also notes inclusion of unfinished boards, distinguishing it from a generic list tool, though it doesn't explicitly contrast with retro.boards.search.

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

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

It gives clear context about when to include team_id ('Pass team_id when several teams are available') and how to filter by period via since/until. No explicit mention of alternatives like retro.boards.search, but the conditional guidance for team_id is specific.

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 readOnlyHint annotation already declares this as a safe read operation. The description adds valuable behavioral context by explaining that cards hidden by private writing during an ongoing retro are excluded, which informs expectations about result completeness.

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

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

The description is two concise sentences with the primary action front-loaded. It includes the key scope and a relevant exclusion rule without any redundant or filler content.

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

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

Given the tool has only two well-documented parameters, readOnly annotation, and no output schema, the description covers the essential operational aspects: what is searched, the optional filter, and an important exclusion. It could mention the result format or pagination, but that is not critical for a search tool.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents query and team_id. The description reiterates the query scope and team filter but does not add new parameter-level semantics beyond the exclusion caveat, which is more about result behavior than parameter meaning.

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 ('Search') and clearly identifies the resource scope ('across retrospectives') and the content searched (board summaries, action items, participant cards). This clearly distinguishes it from sibling tools like retro.boards.list (listing boards) and retro.board.summary.get (fetching a single summary).

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 states clear usage context: searching by keyword across retrospectives with an optional team filter. It does not explicitly name alternatives or when not to use, but the scope and filtering option make the intended use evident.

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 empty annotations, the description carries the full burden. It discloses the mutation (turns suggestion into action item), the state change (marks accepted), preservation of wording/link, and the required scope. This is good coverage, though it doesn't mention error behaviors such as failure if the suggestion isn't pending.

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

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

Two sentences, no redundant wording. The first sentence explains the core action with important detail, and the second adds a necessary permission note. 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?

Given the tool's simplicity and the rich schema, the description is sufficient for an agent to select and invoke it. It explains the source, mutation, side effect, and permission. The absence of an output schema means the return format is not described, but the lack of explicit return value 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 description coverage is 100%, and each parameter already has detailed meaning (e.g., suggested_action_id from insights.list, only pending). The description adds context about the overall process but doesn't add parameter-specific semantics beyond what the schema provides, 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 clearly states the tool's function: converting a pending suggested action into a real action item. It specifies the source (retro.board.insights.list), the outcome (marks as accepted), and how content is preserved (wording and cluster link). This distinguishes it from sibling tools like reject and manual creation.

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

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

The description provides clear context for when to use it: for pending suggestions from insights.list that should become actionable. It mentions the prerequisite of mcp:write scope and that only pending suggestions are eligible (in schema). However, it doesn't explicitly compare to alternatives like retro.board.suggested_actions.reject or retro.actions.create, so it lacks explicit when-not-to-use 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?

The description discloses the state change to rejected, that no action item is created, and the required mcp:write scope. Since annotations are empty, this carries the transparency burden adequately, though reversibility and error behavior are not discussed.

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

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

The description is two sentences, front-loaded with the action and effect, and includes the permission scope in a compact second sentence. No wasted words.

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

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

For a simple reject action with a complete schema and no output schema, the description covers the outcome and permission requirement. Minor gaps like error handling are not mentioned, but the schema covers status restrictions.

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 cover both parameters fully (100% coverage). The description adds only a hint that the ID comes from insights.list, but the schema already specifies the 'pending' restriction. No significant extra meaning is added.

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

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

The description clearly states the action: 'Rejects a pending suggested action from retro.board.insights.list', with a specific verb and resource. It also explains the outcome ('moves to rejected and no action item is created'), distinguishing it from the sibling promote 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 implies the tool is for rejecting pending suggestions, and the scope requirement is provided. However, it does not explicitly mention alternatives or when not to use this tool, though the context makes it 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?

The annotations already declare readOnlyHint=true, and the description adds valuable context about the null summary for unfinished boards and the need to check is_finished. It also hints at return content (participant info and metadata), going beyond the safety annotation.

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

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

The description is concise and front-loaded, stating the primary purpose in the first sentence and adding a critical caveat in the second. Every word earns its place, with no redundant information.

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

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

For a simple get-by-ID tool with one parameter and no output schema, the description adequately covers the main behavior, including the null-summary edge case. It could be more explicit about the exact structure of participant info and metadata, but overall it is sufficient for an agent to use 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%, with board_id fully described. The description does not add any additional meaning to the parameter beyond what the schema provides, so it meets the baseline but does not exceed 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 clearly states it returns the summary of a retrospective with participant info and metadata, using a specific verb and resource. It distinguishes itself from sibling tools like retro.board.health.get and retro.board.roti.get by explicitly focusing on the summary and its contents.

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

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

The description provides clear context by noting that it works for unfinished boards and that summary is null until wrapped up, implying when to expect meaningful data. However, it does not explicitly mention alternative tools or when not to use this tool, so it falls short of a perfect score.

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 readOnlyHint annotation already indicates a safe read, but the description adds significant behavioral context: the output represents the team roster from settings, the meaning of the id for downstream tools, and what it does NOT include (card authorship). This goes well beyond the minimal annotation.

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 dense sentences with no fluff. It front-loads the return type and fields, then provides usage context and edge-case handling. Every sentence adds value and the structure is 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?

For a simple read-only list tool with one optional parameter and no output schema, the description covers the return fields, role enum, downstream usage, team_id omission rule, and a distinction from card authorship. It is entirely adequate for an agent to invoke 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% for team_id, including the prerequisite to call retro.teams.list first. The tool description repeats this information without adding new parameter semantics, so it meets the baseline for full schema coverage but does not exceed 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 clearly states the tool returns team members with specific fields (id, name, role) and explicitly distinguishes it from card authorship, which aligns with sibling tools like retro.board.actions.list. The verb 'Returns' and resource 'members of a team' make the purpose unequivocal.

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 guidance: 'Use the id as assign_to in retro.actions.create, retro.actions.update and retro.board.suggested_actions.promote.' Also gives a clear exclusion: 'it says nothing about who wrote which card' and advises on team_id handling ('Pass team_id when several teams are available; with a single team it can be omitted').

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?

While annotations already mark the tool as read-only, the description adds context about the boards_count field's meaning, helping interpret the output. No contradiction with 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 sentences, front-loaded with the purpose, and includes a helpful clarification without redundancy.

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

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

For a simple no-parameter list tool, the description covers the primary purpose, key field semantics, and points to a sibling for finer-grained board counts, making it 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 tool has zero parameters, so the baseline is 4. The description adds no parameter information because none exists.

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 list of teams the user belongs to, using a specific verb-resource combination. It also distinguishes itself from retro.boards.list by clarifying the boards_count field meaning.

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

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

The description explicitly points to retro.boards.list as an alternative when needing to differentiate finished and unfinished boards, providing guidance on when to use this tool vs the sibling.

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