Server Quality Checklist

Tool Scores

• taskops_takeB
  3.3/5.0
  Behavior3/5

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

  The description discloses that claiming returns a bundle of information (goal, spec, thread, notes, collisions, worktree) and restricts use to workers, which adds useful behavioral context given no annotations. However, it does not mention the side effect of claiming (e.g., assigning the card to the caller, possibly locking it), leaving a transparency gap.

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

  Conciseness4/5

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

  The description is a single sentence that front-loads the core action ('Claim your card') and then lists the returned items compactly. It is efficient with no obvious fluff, though the long list makes it slightly dense. The structure is appropriate for the information conveyed.

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

  Completeness2/5

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

  Given the tool has nine parameters, no output schema, and no annotations, the description is under-specified. It omits the create-and-claim functionality implied by the title parameter, does not describe the return format in a usable way, and fails to explain conditional parameter usage. The description covers only the most basic claim action, leaving substantial gaps.

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

  Parameters3/5

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

  The schema covers all nine parameters with detailed descriptions (e.g., actor explains sub-agent MCP sharing, repo_path explains host pinning), so the schema itself provides strong parameter meaning. The tool description adds no parameter-specific information, meeting the baseline for high schema coverage but not exceeding it.

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

  Purpose4/5

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

  The description uses the concrete verb 'Claim' and identifies the resource as 'your card', and it lists specific returned artifacts (milestone goal, spec, thread, etc.). This clearly conveys the tool's primary function. However, it does not explicitly differentiate this from sibling tools like taskops_assign or taskops_update, so the distinctiveness is not fully highlighted.

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

  Usage Guidelines3/5

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

  The phrase 'Workers only' gives a clear audience restriction, and 'Claim your card' implies the main use case. But it does not state when to use this tool instead of alternatives, nor does it mention the create-and-claim behavior described for the title parameter. Guidance 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.

• taskops_boardA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of disclosing behavior. It explains that results are grouped by the required move and lists the group labels, which is useful. However, it does not explicitly state that this is a read-only operation or describe any side effects, return format, or pagination behavior.

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

  Conciseness5/5

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

  The description is a single sentence plus an imperative, with no wasted words. It is front-loaded with the tool's purpose ('THE pulse') and immediately follows with the grouping detail. Every element earns its place.

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

  Completeness3/5

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

  There is no output schema, so the description should explain what the tool returns to be complete. It lists the group names but does not say what each group contains (e.g., card count, IDs), nor how parameters like 'window' or 'milestone' alter the result. The tool is usable but leaves some ambiguity.

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

  Parameters3/5

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

  The input schema has 100% description coverage, so all five parameters are documented. The description adds no additional parameter-level detail beyond the schema, such as how the window or milestone affects the grouping. Since the schema handles parameter semantics, the baseline of 3 applies.

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

  Purpose4/5

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

  The description clearly indicates this tool provides an overview of the board's current state ('what the board is waiting for') grouped by required actions. It distinguishes itself from sibling action tools (take, merge, etc.) by being a high-level status read. However, it lacks an explicit verb like 'get' or 'list', relying on implication.

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

  Usage Guidelines4/5

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

  The instruction 'Open every turn with this' provides clear timing for when to use the tool. It does not explicitly exclude cases or name alternatives, but the grouping of moves implies it should be used before acting on specific cards. A stronger version would mention using it before taskops_take or taskops_merge.

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

• taskops_activityA
  3.9/5.0
  Behavior3/5

  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 what is returned (standing, commits with numstat, merged_into, notes), how depth changes output, and that diffs are not included. However, it does not mention side effects (likely none but not stated), auth requirements, or rate limits, and it doesn't explicitly confirm read-only behavior.

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

  Conciseness5/5

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

  Three sentences pack a lot of value: the first gives a clear overview, the second explains filters and depth, the third sets a critical limitation. There is zero fluff and every phrase earns its place, making the description appropriately sized for a complex read tool.

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

  Completeness4/5

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

  Without an output schema, the description must communicate return value essence, which it does by enumerating card standing, commits, merge info, and reports. The schema covers parameter details thoroughly, so the description need not repeat them. Minor gaps remain (e.g., error behavior or how to interpret seq) but the overall package is solid.

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

  Parameters4/5

  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 meaningful layer: 'since=<seq> returns only what moved' and 'depth=full adds each spec and thread' reinforce the semantics. The milestone/tasks filter explanation also helps, going slightly beyond the raw schema.

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

  Purpose4/5

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

  The description clearly states it provides 'the whole story of a chapter in ONE read' including cards, commits, merge locations, and reports. While it lacks a direct verb like 'list' or 'get', the intent is unambiguous and the content distinguishes it from sibling tools like taskops_board or taskops_card.

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

  Usage Guidelines4/5

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

  It explicitly covers when to use it (for a comprehensive chapter view), how to limit scope (milestone, tasks), and how to do incremental reads (since=<seq>). The 'No diffs' note tells users to go to git for diffs, acting as a clear exclusion. It doesn't name alternative sibling tools, but the guidance is practical.

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

• taskops_assignA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description must carry the burden. It discloses mutating actions (assigning cards, cutting worktrees) and sub-agent spawning, but lacks detail on reversibility, permissions, or failure behavior. It gives core behavior without deep consequences.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the main action, no redundant words. Efficiently packs the workflow into a readable format.

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

  Completeness3/5

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

  The tool is complex (multi-step, sub-agent spawning) and there's no output schema. The description mentions returning paste-ready briefs but not their structure or additional side effects. It's adequate but lacks depth for a task of this complexity.

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

  Parameters3/5

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

  All parameters have schema descriptions (100% coverage), so the description doesn't need to add parameter info. It mentions 'cut one worktree each' which aligns with the worktrees parameter, but adds no new semantics beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool's function: assign cards to workers, cut worktrees, return paste-ready briefs, and spawn sub-agents. The verb 'assign' and specific actions distinguish it from sibling tools like taskops_take or taskops_update.

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

  Usage Guidelines4/5

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

  'Orchestrator only' provides explicit context on who should call it, and 'spawn one sub-agent per brief' implies it's for delegation workflows. However, it doesn't name alternative tools or specify 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.

• taskops_cardA
  3.9/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the behavioral burden. It clearly discloses the return scope (full card with spec, thread, graph, file collisions, worktree) and the search fallback, which strongly implies a read-only operation. It does not mention error behavior or auth, but the read intent is well conveyed.

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

  Conciseness5/5

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

  Two short sentences, front-loaded with the primary purpose and a list of contents. Every phrase adds useful information; there is no filler or redundancy.

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

  Completeness3/5

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

  The description is readable and informative for a retrieval tool, but it omits the expected relationship between task and query (e.g., whether they are mutually exclusive) and does not explain behavior when neither is provided. Since there is no output schema, the lack of return-format details is also a gap, though the explicit list of included data partially compensates.

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

  Parameters3/5

  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 restates the query behavior already in the schema ('search titles and specs') and adds no extra meaning for task, actor, or repo_path beyond the schema's own detailed descriptions.

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

  Purpose5/5

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

  The description opens with 'One card in full' — a specific verb+resource — and enumerates the full contents (spec, thread, graph, file collisions, worktree). It also distinguishes a second mode (query search) and implicitly separates this tool from siblings like taskops_board or taskops_activity.

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

  Usage Guidelines3/5

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

  The description implies usage: use it to view one card in full, or use query to search titles/specs. However, it never explicitly states when to prefer this over sibling tools, nor does it explain consequences of omitting both task and query.

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

• taskops_planA
  3.9/5.0
  Behavior3/5

  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 usefully discloses the one-call batch behavior and the critical indexing rule for `after` and `parent`. However, it does not mention what happens on failure, whether the operation is idempotent, what the return value is, or any permission prerequisites beyond 'Orchestrator only.'

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

  Conciseness5/5

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

  The description is only two sentences, both information-dense. It front-loads the core purpose and then gives the two most important invocation constraints (index-based dependencies, orchestrator-only). No filler or redundant restatement of schema details.

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

  Completeness3/5

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

  This is a complex tool with 8 parameters, a nested `tasks` array, and no output schema, yet the description is quite terse. It captures the fundamental tree-creation model and the indexing convention, which is helpful. But it doesn't explain what the call returns, how existing milestones/cards are handled (create vs update), or provide an example, leaving some practical ambiguity for an agent.

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

  Parameters3/5

  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 parameters well. The description restates the indexing rule for `after` and `parent`, which is already present in the schema, and adds no new parameter-level meaning beyond that. This meets the baseline for high schema coverage but doesn't exceed it.

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

  Purpose5/5

  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: 'Write the tree in ONE call: a milestone and its cards, dependencies included.' It clearly distinguishes this from sibling tools like taskops_card by emphasizing the one-call batch creation of a milestone plus cards. The addition of 'Orchestrator only' further clarifies the intended caller.

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

  Usage Guidelines4/5

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

  The description states 'Orchestrator only,' which gives an explicit exclusion for when this tool should be used. It also implies this is the batch alternative to single-card tools by saying 'Write the tree in ONE call.' However, it doesn't explicitly name alternative sibling tools or describe scenarios where one would prefer taskops_card over taskops_plan.

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

• taskops_filedA
  4/5.0
  Behavior3/5

  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 does add valuable context with 'The board stores the pointer, never the prose — every reader renders it from its own clone,' which explains the storage model beyond the schema. Yet it leaves unspecified whether registration is idempotent, what happens on duplicate paths, and what output or errors are returned.

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

  Conciseness5/5

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

  The description is exactly two sentences: the first compactly packs the required parameters and the prerequisite into a single line, and the second explains the pointer-based storage model. Every clause is purposeful with no filler or redundancy.

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

  Completeness4/5

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

  The core concept is well covered: the tool requires an existing commit, stores only a pointer, and renders from each reader's clone, with a sensible milestone default. It does not discuss output/return behavior or error cases, but for a simple registration operation with fully documented parameters this is a minor 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.

  Parameters3/5

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

  Schema coverage is 100% and each parameter already has a descriptive comment, so the description's inline list 'path=, title=, sha=, milestone=' adds no new semantic detail beyond restating names. The milestone default is also repeated from the schema, so the description does not elevate parameter understanding.

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

  Purpose5/5

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

  The description opens with an explicit verb ('Register') and a specific resource ('a report you already COMMITTED under .taskops/reports/'), immediately clarifying that this tool records a commit pointer rather than storing content. This operationally distinguishes it from siblings like taskops_card or taskops_review, which handle different board actions.

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

  Usage Guidelines4/5

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

  The description clearly states the prerequisite (the report must already be committed) and notes the milestone default ('the single open chapter'), giving the agent a concrete condition for when to use this tool. However, it does not name alternative tools or explicitly say when not to use it, so it stops short of full exclusion guidance.

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

• taskops_updateA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses status-transition constraints (done needs a commit, released requires a note, dropped needs a reason), the semantics of note being shown verbatim to the next worker, and the actor requirement for sub-agents. It stops short of stating permissions/reversibility, but the covered behavior is substantial.

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

  Conciseness5/5

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

  The description is a single dense sentence list, front-loaded with 'Change the CARD' and then compactly enumerating operations and constraints. Every clause adds information and there is no filler or repetition of schema content.

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

  Completeness4/5

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

  For an 18-parameter tool with no output schema, the description plus the rich per-parameter schema descriptions cover the main workflows and special cases (milestone-only updates, actor identity, repo_path). It doesn't mention return values or advanced combinations, but the schema compensates and the core lifecycle is well explained.

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

  Parameters3/5

  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 mostly rephrases what the schema already says (e.g., status requirements, note requirements). It adds modest value by summarizing the lifecycle in one place, but it doesn't go beyond the schema to explain parameter meanings.

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

  Purpose5/5

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

  Description opens with a specific action ('Change the CARD') and enumerates concrete operations: close, hand in for review, hand back, drop, retitle, rewrite spec/criteria, reprioritise, declare a dependency. This clearly identifies the tool as the mutation entry point for cards and distinguishes it from taskops_comment, which is named as the channel for merely saying something.

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

  Usage Guidelines4/5

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

  Provides explicit usage context: status=done requires a commit or no_code=true, review requires status=review, released/dropped require notes, and it explicitly directs casual communication to taskops_comment. It doesn't map out all sibling alternatives (e.g., taskops_review), but the lifecycle guidance gives clear when-to-use signals for the main operations.

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

• taskops_reviewA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description discloses important behaviors: 'one verifier per card' (exclusivity), 'full dossier back' (return info), 'the worker's lease untouched' (no impact on worker), 'note reaches the worker verbatim' (note transparency), and the self-review ban. This is substantial context beyond the schema.

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

  Conciseness4/5

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

  The description is two sentences and front-loads the tool's purpose. It uses cryptic capitalization and punctuation, but every clause adds information. It could be clearer on the two-step process.

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

  Completeness4/5

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

  The tool has no output schema and no annotations, so the description must cover behavior. It explains the claim vs judge modes, the exclusivity, the dossier return, and the self-review rule. However, it doesn't detail the structure of the 'full dossier' or error conditions, but for a 5-param tool with schema descriptions, it's reasonably complete.

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

  Parameters4/5

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

  The description adds meaning to key parameters: task is the submitted card, verdict accepts pass|changes, and note is passed verbatim. The schema already has detailed descriptions for all 5 parameters (100% coverage), so the description builds on that by explaining the workflow.

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

  Purpose5/5

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

  The description clearly identifies this as the verification/review tool: 'THE verifier's one door' and explains it claims a submitted card and judges it with verdict=pass|changes. It distinguishes implicitly from siblings by being the only review tool.

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

  Usage Guidelines4/5

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

  It states the workflow: claim a card (task=...) and then judge with verdict and note. It adds a key constraint: 'You may never judge your own work.' However, it doesn't explicitly compare to alternatives beyond calling itself the 'one door', but the workflow is clear.

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

• taskops_commentA
  4.5/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the burden and does so impressively. It discloses that mentions reach the recipient on their next call and clear themselves when the recipient writes, and it warns about cross-project repo_path requirements and the need for sub-agents to pass actor. These are critical behavioral traits beyond the schema.

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

  Conciseness5/5

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

  The description is three sentences with no filler. It front-loads the core action, then provides value about mentions and the parallel-agent channel. Every clause earns its place, using emphasis (caps) judiciously to communicate importance.

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

  Completeness5/5

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

  Given five parameters, no annotations, and no output schema, the description covers the essential context: core purpose, mentions behavior, cross-project usage, and agent identity pitfalls. It is sufficient for an agent to understand when and how to invoke the tool without additional information.

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

  Parameters3/5

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

  The schema provides 100% coverage with detailed descriptions for all five parameters, so the baseline is 3. The main description adds little beyond the schema, though it does highlight the mentions feature and the cross-project behavior. It does not compensate further but also does not need to.

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

  Purpose5/5

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

  The description opens with 'Say something on ANY open card', which is a specific verb and resource. It further distinguishes itself by emphasizing its role as 'THE channel between agents in parallel' and the ability to mention others, making it clearly different from sibling tools like update or card.

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

  Usage Guidelines4/5

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

  It provides clear context for when to use the tool: 'when your files meet theirs, say so on their card' and mentions that it reaches the recipient on their very next call. However, it does not explicitly list alternatives or when not to use, so it lacks exclusions but still gives strong usage cues.

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

• taskops_mergeA
  4.7/5.0
  Behavior4/5

  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 reveals the merge strategy (--no-ff), the worktree context, batch stop/continue semantics, conflict handling ('aborts clean'), and the guarantee about main. It does not cover every edge case (e.g., what happens if a card is not DONE), but the key behaviors are transparently disclosed.

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

  Conciseness5/5

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

  The description is three dense sentences, each earning its place. It front-loads the core action, then covers batch behavior, safety, and usage restriction. No filler words or repetition.

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

  Completeness5/5

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

  Given the tool's complexity (7 parameters, no output schema, no annotations), the description plus detailed schema provide sufficient context. It explains batch failure handling, conflict behavior, who should call it, and the safety invariant. The schema descriptions fill in parameter-level detail. The only minor gap is the exact return structure, but 'reports per card' gives a usable expectation.

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

  Parameters4/5

  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 beyond the schema by mapping parameters to usage patterns: 'task= one, tasks=[…] those in order, done=true every card waiting under MERGE'. This gives the agent concrete guidance on how to combine parameters. Additionally, schema descriptions themselves are unusually rich (e.g., actor explains sub-agent identity scenarios), so the overall parameter semantics are strong.

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

  Purpose5/5

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

  The description clearly states the tool's verb and resource: 'Integrate DONE cards into their milestone branch', and adds specificity with '--no-ff, in the integration worktree'. This distinguishes it from sibling taskops tools which mostly manage cards, boards, or activities, whereas this tool integrates completed cards.

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

  Usage Guidelines5/5

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

  Explicitly states 'Orchestrator only', defining who should invoke it. It also explains when to use it ('every card waiting under MERGE') and describes the batch processing behavior ('stops at the first failure, reports per card, and continues on a re-run') which tells the agent how to handle partial failures. The safety note 'main is never touched' gives an important usage boundary.

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