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

With no annotations, the description carries the full burden and does disclose real side effects: board-sync items are enqueued for every task and a Slack notification is posted. It still omits permission requirements, idempotency/reversibility, and failure behavior for a state-mutating admin tool.

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

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

Two sentences, zero padding, and the state transition is front-loaded ahead of the side effects. Every clause carries information.

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

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

The side-effect disclosure is strong for a mutation tool lacking annotations and an output schema, but the 0% parameter coverage and absence of any auth, error, or idempotency notes leave gaps an agent would want before invoking an admin action.

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 0%, so the description must compensate for both parameters and does not. PlanId is self-evident from its name, but as_agent is never explained and no format, validity, or default guidance is added anywhere.

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

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

States a specific verb and resource plus the exact state transition ('move a plan from draft to active'), which is more precise than a bare 'activate'. It does not differentiate itself from lifecycle siblings like create_plan or archive_plan, but the action is unambiguous.

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

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

The 'Admin:' prefix implies a privileged context and the draft-to-active framing implies when it applies, but there is no explicit when-not-to-use or pointer to alternatives such as create_plan or archive_plan. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden. It does disclose one meaningful trait — that this is an admin-scoped operation (privilege requirement) and that phases are optional — but says nothing about mutation semantics, ordering conflicts, duplicate handling, or reversibility.

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

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

Two short, front-loaded sentences with no filler. The second sentence is not padding — it clarifies the optional role of phases, which matters for deciding to call this at all.

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 mutation tool with zero schema descriptions, no annotations, and no output schema, the definition is far too thin. An agent gets no guidance on OrderIndex, as_agent, or the success/failure outcome of the call.

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 0% across 4 parameters, so the description must compensate and does not. It only loosely implies PlanId; OrderIndex (ordering semantics, collision behavior) and as_agent (impersonation?) are entirely unexplained.

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

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

States a specific verb+resource ('add a phase to a plan'), which is clearly distinct from the task-centric siblings like create_task and claim_next_task. It does not name a sibling alternative, but the operation is unambiguous.

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

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

The 'Admin:' prefix signals privileged/contextual usage, and 'Phases are an optional structural layer; tasks may be unphased' hints that this step is not always needed. However, it never states when to use this versus create_task/create_plan, and gives no prerequisites or 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?

No annotations exist, so the description carries the full burden. It usefully discloses the admin-only nature and a real operational precondition (Status option ids must already be discovered via GraphQL), but says nothing about idempotency, what happens if the board is already registered, auth requirements, or the effect of the optional status mappings.

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 efficiently written sentences, front-loaded with the 'Admin:' qualifier and the prerequisite. Every clause carries information; there is no filler.

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

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

For a 12-parameter mutation with no annotations, no output schema, and zero schema descriptions, the definition does far too little. An agent still lacks the meaning of most parameters, the registration semantics, and the return 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 description coverage is 0% across 12 parameters. The description hints that the StatusOption*/StatusFieldNodeId values come from GraphQL discovery, which partially explains roughly half the parameters, but ProjectId, GithubProjectNumber, GithubOwner, DisplayName, and as_agent are entirely undocumented in both places.

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

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

States a specific verb and resource: 'register a GitHub Projects V2 board for a project.' That resource is distinct enough from siblings like add_project_repo and set_project_slack that an agent can tell what is being attached, though it never explicitly contrasts itself with those siblings.

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

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

The 'Admin:' prefix and the note that the caller must have already discovered Status field option ids imply a prior setup step in a flow, but there is no explicit when-to-use versus when-not-to-use guidance and no named alternative among the sibling tools.

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

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

With no annotations, the description carries the full burden, and it does add two real behavioral facts: this is an admin-only operation, and reference-only repos are not modified by the system. It omits idempotency, what happens on duplicate attachment, and whether the repo must pre-exist, so coverage is partial rather than complete.

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 tight sentences, front-loaded with the core action and followed by the one non-obvious semantic detail. No filler, though it is brief enough that the brevity borders on under-specification.

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?

A mutation tool with no annotations, no output schema, and 5 undocumented parameters needs substantially more: permission details beyond the 'Admin' label, effect on the project, and return/confirmation behavior. The reference-only note is the only substantive addition.

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 0% across 5 parameters. The description only indirectly explains IsReferenceOnly (reference-only repos are not modified) and implies GithubRepo/GithubOwner via 'GitHub repo'; ProjectId and as_agent are left entirely undocumented, so the description does not compensate for the coverage gap.

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

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

States a specific verb and resource: 'attach a GitHub repo to a project', plus an 'Admin:' scope qualifier that frames the privilege level. It is distinguishable from siblings like create_project or add_project_board, though it never names an alternative explicitly.

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

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

There is no when-to-use / when-not-to-use guidance and no alternatives named. The reference-only clause hints at a scenario (upstream project used as a design reference) but frames it as a behavioral note rather than a selection rule, so an agent gets no routing help among the many project-related siblings.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it names the required permission (can_archive_plan), lists the exact tools that will reject the plan with the structured plan_archived error, discloses idempotency and irreversibility, confirms data retention (tasks, events, board cards intact), and notes the Slack side effect.

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 dense but front-loaded, leading with purpose and permission before enumerating rejected tools, lifecycle behavior, and the Slack/return details. Almost every sentence adds distinct value, though the volume could be trimmed slightly without losing substance.

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 mutation tool with no annotations and no output schema, the description fully covers prerequisites, side effects, error behavior, and even return values (plan id, new status, resolved outcome, already_archived). Nothing an agent needs to invoke it correctly 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 0%, so the description must compensate. It explains Outcome ('Completed' default or 'Canceled', suffixing the audit milestone title and appearing on Slack), Reason (shown on the Slack notice), and PlanId implicitly as the target plan. Only as_agent is left undocumented, so it substantially covers three of four parameters.

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 gives a precise verb+resource ('Archive (disable) a plan') plus the immediate effect ('so it stops accepting work'). It clearly distinguishes this from siblings like activate_plan, create_task, and cancel_audit by naming the exact tools and behaviors an archived plan blocks.

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

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

It states when to use it ('retire a finished or abandoned plan') and explains the downstream consequence (the next orchestrator bootstrap creates a fresh plan, enabling a new audit/development pass). It also clarifies it is one-way and idempotent, removing ambiguity about repeated 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?

With no annotations, the description carries the full burden and does well: it discloses the async queue path (audit-dispatch outbox), the background worker signaling the session, that cancellation is cooperative rather than a hard kill, and the orchestrator's /audit-cancel cleanup. It stops short of stating auth/permission requirements precisely or idempotency/behavior for already-finished audits.

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, front-loaded with the purpose, then parameter instruction, then behavior. Dense but each sentence carries information; the outbox/worker detail is slightly verbose but earns its place as behavioral disclosure.

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

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

No output schema, so the description helpfully states the return shape (per-project status 'queued' or 'unknown_project'). For a two-param, no-annotation tool the picture is nearly complete; the gap is the unexplained `as_agent` parameter and the fact that `projects` is described as needed while required is empty.

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 0% and the schema only declares bare types, so the description must compensate. It explains that `projects` accepts a list of slugs or ids, but the casings differ (`projects` vs schema's `Projects`) and `as_agent` is never described, leaving one of two parameters undocumented.

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

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

States a specific verb and resource ('cancel a running audit') plus scope ('one or more projects') and a privilege qualifier ('Admin:'). It is trivially distinguishable from its inverse sibling request_audit without opening a schema.

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

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

The 'Admin:' prefix and 'running audit' phrasing imply the context for use (an in-progress audit needing cancellation by an operator), but no explicit when-to-use/when-not guidance or named alternative is given. Usage must be inferred.

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, and it does disclose that the surface is inert in v1. However, it never says what happens if an agent calls it anyway (error, empty result, no-op), and it does not reconcile that with the schema still requiring PlanId. The mutation/claim semantics of a real version are left unspecified.

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

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

Two tight sentences with no filler; the reserved/future status is front-loaded, followed by the v1 routing rationale. Nothing is wasted, though it could have used its length to cover the required parameter instead.

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

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

For an inert placeholder with no annotations and no output schema, the description conveys enough that an agent should not rely on it. But the required PlanId and as_agent parameters are unexplained, and there is no statement of call behavior, leaving a real gap for anyone who invokes it by name.

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 0% and the description mentions neither PlanId (required) nor as_agent. It references 'the attempt id', which is not even a parameter of this tool, so it actively fails to explain the two parameters the agent must supply.

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

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

The description names the resource (a reserved claim surface for the fix-verifier / dev-reviewer queue) and explicitly frames it as a future/placeholder tool. It also names the sibling tools (submit_attempt_verdict / submit_review_decision) that supersede it in v1, so an agent can distinguish it. It stops short of a 5 because it never states what the tool would actually return or do if invoked.

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

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

It gives explicit when-not guidance: no separate claim is needed in v1 because the verdict tools accept the attempt id directly from orchestrator state. That is a clear routing instruction. It lacks an explicit 'use X instead' call-to-action and gives no condition under which this tool would ever be the right choice.

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 usefully discloses the side effect ('sets the finding status to in_fix as part of the claim transaction') and the implicit role assignment ('Caller is implicitly the fixer'). It omits edge behavior such as what happens when no eligible finding exists, locking/exclusivity, and whether the claim must later be released.

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 waste, and the 'Audit-plan-only' scope constraint is front-loaded. Efficient 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?

No annotations or output schema exist, so the description must carry more. It adequately explains the claim semantics and the in_fix state transition, but leaves parameters undocumented and omits failure/empty-queue behavior, so it is not fully complete for a bare 2-param mutation 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 0% and neither of the two parameters is documented in the description. 'Audit-plan-only' loosely implies PlanId is an audit-plan identifier, but as_agent is entirely unexplained and the connection to the implicit 'fixer' role is not made explicit.

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

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

The description states a specific verb and resource ('claim the highest-severity confirmed... finding to fix') and adds scope ('Audit-plan-only'). The 'to fix' framing implicitly separates it from claim_next_finding_for_verification, though it never names the sibling explicitly.

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?

'Audit-plan-only' is a clear precondition, and the finding-selection criteria ('confirmed or below-cap fix_failed/partial, highest-severity') give context. However, it never states when to prefer this over claim_next_finding_for_verification or the release/refresh claim tools, leaving the alternative-selection decision to inference.

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 and does disclose real behavior: severity-ordered selection, implicit assignment of the 'verifier' role for the claim duration, and an explicit empty-result sentinel. It omits the claim lifecycle (lease/expiry, how the claim is released, whether refresh_claim applies) and any 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?

Three short sentences, all front-loaded: scope claim, actor-role behavior, and failure mode. No filler or restatement of the tool name.

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 selection policy, role assignment, and the empty case, which is a lot for a claim tool with no output schema. However, an agent still cannot determine the claim's duration, how to release or refresh it, or what as_agent does, which are material gaps for a state-mutating claim.

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 0% for both parameters. The description implies PlanId via 'on the plan', but 'as_agent' is never explained, and it is unclear whether it overrides the implicit actor-role assignment described in the text. With zero schema-level documentation, the description should compensate and does not.

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

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

States a specific verb (claim), a precisely bounded resource (highest-severity pending-verification finding), and a scope qualifier (audit-plan-only). This cleanly separates it from the close siblings claim_next_finding_for_fix and claim_next_attempt_for_review without the agent needing to open any schema.

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

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

The 'Audit-plan-only' qualifier and 'pending-verification' condition tell the agent exactly which context this applies to, and the no_work_available outcome signals when there is nothing to claim. It stops short of naming an alternative tool to use when no verification work 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?

With no annotations, the description carries the full burden and largely succeeds: it discloses the atomic/concurrent-safe claim behavior, the success return shape ({ task, claim_token }), the no_work_available failure mode, and a real side effect (assigning the bound Project V2 card to the calling actor's GitHub user). It omits claim expiry/TTL behavior and what the token must be used for afterward (release_claim, refresh_claim, start_work), which matters in a claiming system.

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 tight sentences, front-loaded with the core action, then the role constraint, then the return contract, then the usage cue and side effect. Every sentence adds information an agent needs to call this correctly; no padding or restatement of the tool name.

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?

There is no output schema and no annotations, and the description covers the return shape, the failure case, and the attribution side effect, which is what an agent needs to select and invoke it. Remaining gaps are the TTL/expiry semantics tied to TtlOverride and the lifecycle of the returned claim_token across the sibling release/refresh/start tools.

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 0%, so the description must compensate. It meaningfully explains Role (must be valid for the plan's plan_type, with examples) and PlanId implicitly, which is genuinely useful. However as_agent and TtlOverride are never mentioned, leaving half the parameters opaque in both schema and description.

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

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

States a specific verb and resource with explicit selection semantics: "Atomically claim the highest-priority pending task on a plan for the given role." This distinguishes it from the sibling claim_specific_task, since it makes clear the system chooses the task rather than the caller naming one.

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?

"Use this when the orchestrator or developer is ready to start something new and the system should pick" gives a concrete triggering condition. It does not explicitly name claim_specific_task as the alternative for when the caller already knows which task to take, so the routing is implied rather than stated.

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

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

With no annotations present, the description carries the full burden and does well: it discloses the failure mode ('Fails with task_unavailable if another actor holds it with an unexpired claim') and a side effect ('Assigns the bound Project V2 card to the calling actor's GitHub user'). It omits claim TTL/expiry semantics and permission requirements, keeping it below 5.

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, each earning its place: purpose first, then failure condition, then usage context and side effect. Front-loaded and free of 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 4-parameter mutation tool with no annotations and no output schema, the description covers purpose, failure mode, and side effect but leaves three parameters undocumented. It is adequate at the workflow level but incomplete for correct invocation with the optional arguments.

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 0% across four parameters, so the description must compensate — but it explains none of them. 'Claim by id' loosely maps to TaskId, while Role, as_agent, and TtlOverride are left entirely undefined in both schema and description (notably TtlOverride, which relates directly to the 'unexpired claim' behavior mentioned).

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

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

States a specific verb and resource ('Claim a specific task by id'), and the modifier 'specific...by id' cleanly distinguishes it from the sibling claim_next_task, which claims whatever task comes next. An agent can pick between the two without opening either schema.

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

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

Gives an explicit when-to-use condition: 'Use when the orchestrator is directing work (e.g. dispatching a subagent to a particular task).' It implies the contrast with the next-task claimers but never states a when-not or names an alternative tool, so it falls short of a full 5.

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 and usefully discloses draft status, the board-inheritance/sync behavior that fires for every task, the response echo semantics (null = not board-bound), and an admin-auth hint. It still omits what PlanType values are legal, whether creation is reversible, and any error/failure 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?

Board-inheritance guidance is front-loaded and every sentence carries operational meaning, but the second sentence is a long run-on bundling several distinct facts (inheritance, board sync, bulk inserts) that could be split for scanability.

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 creation tool with no annotations and no output schema, the description does cover the primary_board_id lifecycle and partial return semantics, but leaves most parameters, allowed PlanType values, and the non-board side effects of creation opaque to the caller.

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 0% across 7 parameters, yet the description explains only PrimaryBoardId. The required ProjectId, plus Name, PlanType, as_agent, Objective, and PrimarySlackChannelId, remain entirely undocumented, so the description fails to compensate for the coverage gap.

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

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

States a specific verb+resource+initial state: 'create a new plan (in draft status)', with the 'Admin:' qualifier signaling the privilege tier. An agent can distinguish it from activate_plan and archive_plan without opening schemas.

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

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

Gives explicit when/when-not for primary_board_id ('omit when the project has exactly one board; pass explicitly only when more than one') and routes activation to activate_plan. It does not, however, cover the broader when-to-create-a-plan-vs-other-creators 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 no annotations, the description carries the full burden. It usefully discloses the privilege requirement ('Admin') and the identifier semantics of Slug (stable across URLs/CLIs), but says nothing about required fields, uniqueness/idempotency behavior, or side effects on creation.

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

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

Two tight sentences with the core action front-loaded and no filler. Efficient, though the brevity comes at the cost of the missing details noted elsewhere.

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?

A mutation tool with no annotations, no output schema, and 0% parameter coverage needs substantial description support. It covers permission level and Slug semantics but omits required-by-behavior fields, return behavior, and creation side effects.

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 0%, so the description must compensate. It only explains Slug; as_agent, Description, and DisplayName are undocumented in both schema and description. Three of four parameters are left opaque.

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

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

States a specific verb (create) and resource (project), with an 'Admin:' prefix that signals the privilege context. It is clearly distinguishable from create_plan/create_task by resource, though it does not explicitly contrast with those siblings.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives despite several related create_* and list/create-plan siblings. The 'Admin:' prefix only implies who may use it, not when the agent should choose this tool.

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

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

With no annotations present, the description carries the full behavioral burden and does so unusually well: it states the created status (pending), that claim_next_task/claim_specific_task skip tasks with non-terminal predecessors (listing done/deferred/skipped/out_of_scope), that predecessors must share the plan, that cycles are rejected at insert, that the board sync always fires so a draft GitHub Projects V2 item lands in Backlog, and that Slack is opt-in with a stated default and rationale. This is more disclosure than most annotated tools provide.

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 most important fact (what is created, in what status) is front-loaded, and the dependency explanation is grouped coherently before the sync/Slack behavior. It runs long and packs several clauses per sentence, but virtually every sentence carries distinct operational information rather than 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 zero-annotation, no-output-schema mutation tool with 11 parameters, the description covers behavior richly but leaves the majority of the input surface undocumented — notably as_agent, ExternalKey, ReferencePointer, and Paths, which look like they have protocol significance. An agent can call this correctly only for the PlanId/DependsOn/NotifySlack path.

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 0% across 11 parameters, so the description must compensate, and it only does so for two: DependsOn (dependency/skip semantics, same-plan constraint, cycle rejection) and NotifySlack (default false and why). Paths, Title, PhaseId, Priority, as_agent, ExternalKey, ReferencePointer, Description, and PlanId are left entirely unexplained, so an agent must guess at their formats.

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

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

The description opens with a specific verb, resource, and initial state: 'Create a new task on a plan, in pending status.' That is enough to separate it from read/claim siblings like claim_next_task. It does not, however, distinguish itself from the sibling create_tasks (bulk variant), which an agent would plausibly confuse it with.

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 names the callers ('orchestrators that decompose larger work units', 'admin tools that import work from external sources'), which implies usage context, but gives no explicit when-to-use-vs-alternative instruction and never mentions create_tasks or set_project_slack as related tools. The rule 'pass true to post a task.created message' is the closest thing to actionable guidance.

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

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

With no annotations, the description carries the whole burden and does it well: two-pass insert-then-wire processing, cycle rejection semantics (returns the first cycle's task, no rollback, partial state persists, re-run via unique external_keys), unconditional board sync, and Slack defaulting to false to avoid channel flooding. Auth/permission constraints and rate limits are the only undisclosed behaviors.

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

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

Front-loads purpose, then spends every remaining clause on behavior (dependency resolution, failure semantics, side effects). It is a long single paragraph where a bulleted breakdown of the two passes and side effects would scan better, but there is essentially no filler.

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

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

Covers mutation semantics, partial-failure behavior, and side effects thoroughly despite having no annotations or output schema. The main gap is the success return shape (only the cycle-error return is described) and the unexplained as_agent parameter; return values needn't be spelled out only when an output schema exists, which it does not.

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 0% and the schema is bare ('Tasks' is just type array), so the description must compensate — and it does for the critical parts, documenting item-level 'depends_on_ids', 'depends_on_external_keys' and the NotifySlack default. However 'as_agent' is never explained and PlanId is only implied by 'a single plan', leaving two of four parameters undecoded.

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

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

States a specific verb+resource ('Bulk task creation') plus the concrete context ('orchestrator bootstrap, e.g. Phase 0 of an audit') and scope ('a list of tasks on a single plan'). The 'bulk/on a single plan' framing cleanly separates it from the sibling create_task without needing a schema lookup.

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

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

Gives clear when-to-use context (batch bootstrap) and notable usage guidance: idempotent re-runs after a cycle rejection, and opting into Slack only when every task should be announced. It does not explicitly name create_task as the alternative for single-task creation, so it stops just short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does meaningful work: it declares the output is deterministic, that export is one-way so the DB remains the source of truth (i.e. non-mutating), and what the JSON payload contains. It omits permission/auth requirements and any behavior tied to the undocumented as_agent parameter.

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, front-loaded with the core action, then format options, then the one-way caveat. Every sentence earns its place with no filler.

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

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

No output schema and no annotations means the description must do everything, and while the export semantics and return shapes are covered reasonably, the third parameter (as_agent) is entirely undocumented and permissions/identity behavior is unaddressed. Adequate but with clear gaps.

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

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

Schema description coverage is 0% and the Format property has no enum in the schema, so the description's format ∈ {markdown, json} plus the markdown-vs-JSON tradeoff adds genuine value. PlanId is only implied, and as_agent is completely unexplained in both schema and description.

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

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

States a specific verb and resource ("Export a deterministic snapshot of a plan") plus the output forms (markdown/json) and the snapshot's semantics. It is clearly distinguishable in spirit from read siblings like get_plan_dashboard, but it never names an alternative, so it lands just below the top band.

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

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

Gives concrete usage context ("suitable for committing to a repo or pasting into chat") and a directional constraint ("Export is one-way"). It does not, however, say when to prefer this over get_plan_dashboard/list_plans or exclude any scenario.

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 helpfully discloses that the log records every state change with actor and reason, and 'get' implies a read, but it says nothing about ordering, pagination behavior (Limit/Since), auth/impersonation (as_agent), or how large the log can get. Meaningful but incomplete 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 tight sentences: the resource definition is front-loaded, then the investigative purpose. No filler, no repetition of the tool name.

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

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

No output schema and no annotations, so the description has to cover a lot. It conveys what the log contains (state changes with actor and reason), but for a 5-parameter read tool it under-specifies time filtering, pagination, and the as_agent parameter, leaving real gaps for an agent to resolve by trial.

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 0%, so the description must compensate, and it only covers the entity dimension: the entity-kind enumeration directly clarifies EntityType and 'for a specific entity' implies EntityId. Limit, Since (a nested object), and as_agent are left entirely opaque, and the nested Since is especially risky to guess at.

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

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

States a specific verb (get) and resource (forensic event log) scoped to a specific entity, and enumerates the entity kinds (task / finding / attempt / plan / phase). This is clearly distinguishable from retrieval siblings like get_finding or get_plan_dashboard, which return entity state rather than the change history.

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

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

Gives a concrete investigative scenario ('why did this task end up in needs_human_review'), which tells the agent when this tool is the right one. It stops short of naming alternatives or an explicit when-not-to-use, so it is clear context without 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 and does so: it declares this is a plain read, that no claim is needed, that it works even for orchestrators that didn't author the findings (or resumed after restart), that unknown ids yield a structured not_found error, and that the live claim token is deliberately withheld. This is unusually rich behavioral disclosure.

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

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

Three sentences, front-loaded with the return payload and then routing rationale. Dense and largely waste-free, though slightly long for a single-parameter read 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?

No output schema exists, so the description's enumeration of returned fields (severity, symptom, root cause, reproduction steps, status, claim holder, etc.) fully covers what an agent needs to know about the response. Call correctness and error behavior are both addressed.

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 0%, so the description must compensate for two parameters. It clarifies that the id identifies a finding and describes the not_found behavior for bad ids, but says nothing about as_agent. Partial compensation, adequate but incomplete.

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

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

States a specific verb and resource ('Retrieve the full body of a single finding by id') and enumerates the returned fields. It also explicitly distinguishes itself from claim_next_finding_for_verification and claim_next_finding_for_fix, which return only id/task/status/severity.

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

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

Gives explicit when-to-use guidance ('call get_finding to fetch the auditor-authored body a verifier or fixer subagent needs to reproduce the issue'), states the precondition is absent ('No claim is required'), and names the alternatives that return thinner payloads.

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

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

With no annotations, the description carries the full behavioral burden. 'Get' and 'active claims ... currently holds' imply a safe read scoped to the caller, which is meaningful context, but it discloses nothing about return shape, ordering, or how claims in different states are reported.

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, both earning their place, with the resource scope front-loaded before the usage cue. No filler or restatement of the tool name.

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

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

For a zero-required-param read tool with no output schema, purpose and trigger are adequately covered. However, the unexplained as_agent parameter — which the 'calling actor' phrasing muddles rather than clarifies — leaves an agent unsure whether this tool can be pointed at someone else's claims.

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 single parameter as_agent has 0% schema description coverage, so the description must compensate and does not — it never explains what as_agent does. Worse, saying it returns claims 'the calling actor currently holds' arguably conflicts with the existence of an as_agent parameter that would let the caller query another actor's claims.

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

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

States a specific verb+resource: it returns every active claim held by the calling actor, and it enumerates the exact claim types (tasks, findings, attempts in review) and scope (across every plan). That distinguishes it cleanly from siblings like get_stuck_work and get_plan_dashboard without needing either schema.

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

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

Gives an explicit when: 'Use this on session start to recover claims after a Claude restart.' It does not name a when-not condition or an alternative sibling, so it stops short of full routing guidance, but the trigger context is clear and actionable.

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

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

With no annotations, the description carries the full burden and does so well: it defines stuck work as "claims older than 2× their TTL", caps returns (up to 5 tasks, 20 events), and discloses the 5-second in-process cache with LISTEN/NOTIFY invalidation. It doesn't state that the call is read-only or note any authorization requirements, which keeps it from a 5.

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 dense sentences with zero filler, front-loading the payload contents before the usage and caching notes. Every clause carries information an agent needs.

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 no output schema and no annotations, the description does the heavy lifting by enumerating the returned sections and cache behavior. The main remaining gap is the meaning of as_agent and whether the operation is a pure read, which would round out an otherwise complete definition.

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 0% and two parameters exist, so the description must compensate. PlanId is self-evident, but as_agent is never explained; the phrase "the caller's currently-held claims" only weakly hints that it sets caller identity. The identity semantics of as_agent are left entirely to inference.

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

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

The description names a specific resource (one plan's dashboard) and enumerates exactly what the snapshot contains: per-status counts, per-phase counts, next-claimable tasks, caller's claims, stuck work, and recent events. This aggregation role distinguishes it from focused siblings like get_stuck_work, get_event_log, and get_my_active_work without the agent needing to open any schema.

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

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

"This is the single call an orchestrator makes every iteration to decide what to do next" gives a clear, actionable when-to-use condition tied to a concrete workflow. It stops short of naming alternatives to avoid (e.g., use get_stuck_work for a narrower stuck-work view), so it is a strong 4 rather than a 5.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the exact data categories returned and the scoping options, but says nothing about read-only safety, authorization needs, or result size/volume, which the agent would want before invoking 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?

The purpose is front-loaded and the second sentence handles scoping; there is no filler. The first sentence is a dense colon-list run-on, but each enumerated item is load-bearing because it defines the tool's scope.

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 no output schema, no annotations, and 0% schema description coverage, the description should ideally sketch the response shape and explain as_agent. It covers the content categories and plan scoping well but leaves those gaps for an agent trying to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate. 'Scoped to a single plan or global' effectively explains PlanId (omit to go global), but the as_agent parameter is never mentioned, leaving one of two parameters entirely opaque.

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

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

States a specific verb (view) and resource (stuck work) and then defines exactly what 'stuck' means: tasks past TTL, findings in pending_verification >24h, attempts past TTL, plans with no recent events. That enumeration cleanly separates it from siblings like get_my_active_work or get_plan_dashboard.

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?

'On-demand view of the same data the hourly stuck-work job computes' tells the agent this is the manual counterpart to an automatic job, which is clear usage context. It does not name an alternative tool or state when not to use it, so it falls short of explicit routing guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return payload (per-status task counts) and an efficiency rationale (avoids N dashboard calls), but says nothing about read-only safety, pagination, ordering, or scope/permission limits.

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

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

Two sentences, zero filler, and the core scope statement is front-loaded before the rationale. The second sentence earns its length by explaining both the returned data and why it matters.

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?

There is no output schema, so the description correctly explains what each plan reports, which is the key missing piece. It falls short only on parameter coverage (notably as_agent) and on pagination/ordering behavior for a list operation.

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

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

Schema coverage is 0% and the description only adds meaning for one of three parameters ('optionally filtered by status'). ProjectId is inferable from the prose, but as_agent is entirely unexplained in both the schema and the description, leaving a genuinely opaque parameter undocumented.

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

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

States a specific verb and resource ('List plans on a project') plus the optional filter, so the action is unambiguous. It gestures at the alternative use case ('N additional dashboard calls', implicitly get_plan_dashboard) but never names the sibling, so differentiation is suggestive rather than explicit.

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 second sentence implies the intended use case — pick the next plan with workable work — but never states when NOT to use it or names a concrete alternative such as get_plan_dashboard. Usage is inferable, not spelled out.

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

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

No annotations are provided, so the description carries the full burden. It does disclose meaningful behavior beyond the schema — a visibility filter ('can see') and computed per-project aggregates — but is silent on pagination/result size and does not confirm read-only status except by implication of 'List'.

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

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

Two sentences, both earning their place: the first defines scope and payload, the second defines the usage trigger. Front-loaded and free of 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?

No output schema exists, and the description outlines the returned per-project fields, which is adequate for a read-only list call. The only real gap is unspecified pagination/size behavior and the undocumented as_agent parameter.

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 0% and the single parameter 'as_agent' is never mentioned in the description. The phrase 'the calling actor' hints at actor scoping but does not explain what as_agent does or when to pass it, so the description fails to compensate for the coverage gap.

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?

Specific verb ('List') + resource ('every project the calling actor can see'), with the payload enumerated (active plan count, claimed task/finding counts). This scopes it clearly apart from siblings like list_plans and get_my_active_work without needing to name 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?

Gives an explicit entry-point condition: 'Use this as the first call when a developer or orchestrator wakes up and needs to decide what to work on.' It states when to use it but names no exclusion or alternative tool for the non-wake-up case.

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

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

No annotations, so the description carries the full burden. It discloses the override path, required permission flags (mapping statuses to flags), and concrete side effects (board + Slack notifications). Missing only reversibility or error behavior, but this is a rich behavioral disclosure.

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

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

Front-loaded with the core action and status values, then layers on override/permission/side-effect details. Every clause adds information; no filler. Dense but appropriate for the complexity.

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 a mutation tool with no annotations or output schema, the description covers purpose, permissions, and side effects well. It falls short only on documenting the as_agent parameter and any return/error behavior, but an agent can call it correctly for typical use.

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

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

Schema coverage is 0%, so the description must compensate. It adds valuable enum values for Status and implies Reason, but omits any explanation of TaskId or as_agent. This partially compensates for the coverage gap but leaves key parameters undocumented.

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

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

States a specific verb ('Set') and resource ('task') with an explicit scope: non-normal statuses. Enumerates the allowed status values, so an agent immediately knows what the tool does and can distinguish it from normal claim/work-flow siblings.

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

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

Provides clear context: use for non-normal statuses, bypassing the claim mechanism (override path). Does not explicitly name alternative tools or say when NOT to use it, but the implied contrast with the normal claim flow is strong.

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 load well: it discloses the permission prerequisite, the audit side effect (writes an override event with the supplied reason), and downstream side effects (board + Slack fired for tasks, updating the Project V2 card and channel). It does not address reversibility or failure modes, which leaves one gap for a forced mutation.

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

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

Front-loads the core action and permission requirement, then adds usage and the attempts exception. Four sentences all carry information, though the attempts sentence is long enough that it could be tightened.

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 5-parameter mutation with no annotations and no output schema, the description covers the important unknowns: auth, side effects, when to use, and the sibling to prefer for attempts. It stops short of documenting parameter-level details (as_agent, status vocabulary), which is the remaining 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 0%, so the description must compensate. It conveys that a Reason is recorded and that a status transition occurs, and that the target is a task or finding, but it never explains as_agent, valid NewStatus values, or the EntityType format. Partial compensation only.

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

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

States a specific verb+resource with scope: 'Force a state change on a task or finding without holding its claim.' It names the entities affected (task/finding), the distinguishing mechanism (no claim required), and the artifact written (an override event with a reason), letting an agent separate it from claim-based flows and from mark_task_status.

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

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

Gives an explicit trigger ('Use when a subagent's claim has gone stale but the work it produced needs to be recorded') with a concrete example, and explicit exclusions/routing for attempts ('use record_commit to attach commit metadata; ... override the finding instead'). It also states the precondition — can_override_verdict on the calling actor.

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

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

No annotations, so the description carries the burden. It usefully discloses the side effect ('writes a commit_recorded event') and the post-hoc nature of the operation, but says nothing about permissions, idempotency, or whether attaching a duplicate hash is rejected or overwritten.

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-loaded with the action and scope, followed by the routing condition. No filler, and the most decision-relevant information (what it does, when to use it) comes first.

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 six-parameter mutation tool with no annotations and no output schema, the description covers the 'why' well but leaves most parameter semantics and the mutation's safeguards unstated. Adequate for routing, incomplete for correct invocation.

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

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

Schema description coverage is 0% across 6 parameters, and the description only implicitly clarifies two of them: CommitHash and the EntityType values ('task, finding, or attempt'). RepoId, TargetBranch, and as_agent go entirely unexplained, leaving most of the payload undefined.

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

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

States a specific verb and resource ('Attach a commit hash to a task, finding, or attempt') with a clear temporal qualifier ('after the fact'). It names the sibling flow it deviates from (submit_attempt), so an agent can distinguish it from the normal submit path.

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

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

Explicitly states the triggering condition: use when the commit lands outside the normal submit_attempt flow, with a concrete example (hotfix via override). It names the alternative flow but gives no explicit 'do not use' case or prerequisites.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the token must be live and held by the calling actor, that expired claims cannot be reanimated because the stuck-work sweeper may have reassigned the row, and that a claim_refreshed event is written for audit. It stops short of describing auth/permission requirements beyond caller ownership.

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

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

Front-loads purpose, then usage, then failure-mode caveats and side effects. Dense but every sentence carries operational weight; no filler.

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

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

For a mutation tool with no annotations or output schema, the description covers triggering conditions, default behavior, failure modes, and the audit side effect, which is nearly everything an agent needs. The remaining gap is the unlabeled ClaimToken/as_agent parameters.

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 0%, so the description must compensate. It thoroughly explains ExtendBy (duration shorthand like '30m'/'2h', and the default of adding the role's configured TTL), but ClaimToken and as_agent are left largely implicit. Partial compensation for a 3-param tool.

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

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

States a specific verb and resource: extend an active claim's TTL without releasing it. This clearly distinguishes it from siblings like release_claim, claim_next_task, and start_work, which touch the claim lifecycle differently.

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

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

Explicitly states when to use it ('when a subagent's reproduction is taking longer than the configured role TTL') with a concrete example, and states when it will not work (an expired claim must release and re-claim instead). Both the when and the when-not are covered.

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 and does well: it discloses the status revert to pending, the board card moving to Backlog (with lazy-creation), assignee clearing, and that Slack is deliberately not posted. It omits permissions/auth requirements and error behavior, but the side-effect disclosure is unusually thorough.

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

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

Front-loaded with the core action, then purpose, then consequences, then an intentional non-effect. Every sentence carries distinct information with no filler.

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

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

Behavioral consequences are well covered, but with no output schema, no annotations, and 0% parameter coverage, the definition leaves an agent guessing about the inputs it must supply. Adequate for the mutation semantics, incomplete on the calling contract.

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 0% across 3 parameters, and the description says nothing about Reason, as_agent, or ClaimToken. Only ClaimToken's existence is implied by 'Release a claim'; the optional Reason and as_agent fields remain completely unexplained in both schema and prose.

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

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

States a specific verb+resource ('Release a claim') with the crucial qualifier 'without submitting work,' which immediately contrasts it with the submit_* siblings. An agent can distinguish it from submit_findings or mark_task_status without opening any schema.

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

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

Gives a clear triggering condition: 'Used when an agent decides it cannot complete the work and wants to surface it back to the pool.' This is explicit usage context, though it never names an alternative tool or an explicit when-not-to-use case.

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 and does so well: it discloses the async dispatch via the audit-dispatch outbox, that a background worker launches the orchestrator, that no repo checkout happens for the caller, and the possible return statuses. It stops short of stating explicit permission/auth requirements beyond the 'Admin:' label.

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?

Purpose is front-loaded, then followed by the resolution/dispatch mechanics and result shape. It is fairly dense but each sentence adds operational value; nothing is pure 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 no-output-schema tool, the description usefully explains the return shape (per-project 'queued' with dispatch id and attach_command, or 'unknown_project'). The main gap is the unexplained `as_agent` parameter.

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 0%, so the description must compensate. It explains `projects` well as a list of project slugs or ids, but never mentions the `as_agent` parameter, leaving one of two parameters undocumented in both schema and description.

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

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

States a specific verb (request) and resource (a full audit run for one or more projects), and the 'Admin:' prefix flags the privileged scope. It is clearly distinguishable from the sibling cancel_audit, since this initiates rather than cancels.

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 an admin context and that the caller queues work asynchronously, but it never states when to choose this over alternatives or the conditions under which it should be invoked. Usage is inferred rather than stated.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It indicates an admin-only mutation and names the configurable aspects, but it does not disclose whether existing settings are replaced, how the secret reference is validated, or what permissions/side effects apply.

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

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

The description is a single front-loaded sentence with no wasted words. It puts the admin context and primary configuration targets first. Nothing needs to be trimmed.

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

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

The tool has five parameters, no annotations, no output schema, and 0% schema description coverage. A single sentence naming the main configuration targets is not enough for a mutation tool that needs to convey admin requirements, side effects, and parameter roles such as 'as_agent'.

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 0%, so the description must compensate. It adds semantic meaning for four of five parameters: project, Slack workspace, default channel, and bot-token secret reference. The 'as_agent' parameter remains completely undocumented, which is a meaningful gap.

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 ('configure') and resource ('Slack workspace, default channel, and bot-token secret reference for a project'). It clearly identifies what the tool will change. Sibling differentiation is not explicit, but no sibling tool appears to share this Slack-configuration purpose.

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

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

The description gives no when-to-use guidance, alternatives, or exclusions. The 'Admin:' prefix implies an administrative context but does not say when this tool should be selected over other project-configuration tools.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: a side effect (board sync moves the card to In Progress) and an error outcome (stale token yields stale_claim). It omits permission requirements, idempotency, and what happens if the task is not in 'claimed' state.

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 earning its place: the transition, the side effect, the failure mode. The core action is front-loaded with no filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers the transition, its board side effect, and one error. It leaves the as_agent parameter and any indication of what a successful call returns or how to detect success undocumented.

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 0%, so the description must compensate. It explains ClaimToken well (must be the original, stale tokens fail), but the 'as_agent' parameter is never mentioned and no value format for ClaimToken is given.

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

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

States a specific verb and resource plus the exact state transition ('claimed' to 'in_progress'), which cleanly separates it from siblings like claim_next_task, mark_task_status and release_claim. An agent can identify the tool without opening the schema.

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

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

The precondition is implied by 'a claimed task' and 'requires the original claim token', which tells the agent it must have claimed work first. However, it never names the alternatives (mark_task_status, release_claim, refresh_claim) or states when NOT to use it, so routing is left partly to inference.

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

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

With no annotations, the description carries the burden well: it discloses the state transition (task to review), the attempt-chain side effect on findings, and the retry_cap_exceeded error condition tied to the plan's retry cap. It doesn't mention ClaimToken authorization requirements, but the mutation behavior is otherwise well communicated.

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

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

Three tight sentences, front-loaded with the core action and payload, followed by the branching behavior and error case. The field enumeration is slightly listy but every element earns its place.

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

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

For a mutation tool with a nested Attempt object, 0% schema coverage, and no output schema, the description covers payload contents and error behavior but omits the required ClaimToken role and the as_agent parameter, leaving meaningful gaps an agent would need to infer.

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 0% with three parameters. The description enumerates the fields expected inside the Attempt object, which compensates somewhat, but it leaves ClaimToken (the required param) and as_agent entirely unexplained, so the gap is only partially filled.

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

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

States a specific verb (submit) and resource (attempt at the work) and enumerates the payload (files changed, approach summary, side effects, build command, test scenario, diff reference). It differentiates from the family of related submit_* siblings by clarifying that this records the developer's work attempt rather than a verdict or findings.

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 for when it applies: dev-plan tasks transition to review, while audit findings append to the findings attempt chain. It stops short of explicit exclusions or naming when to prefer submit_attempt_verdict or submit_findings instead.

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

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

No annotations are provided, so the description carries the full burden, and it does a good job: it discloses the state transitions the call triggers, the conditional commit_hash requirement, the retry cap, and the auto-creation of a child finding. It omits authorization/role constraints and the meaning of as_agent, but the mutation side effects are unusually well documented.

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 tightly packed sentences, each earning its place: the first frames the tool, and the rest enumerate verdict-specific behavior. Front-loaded and free of 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 state-machine mutation with no output schema and no annotations, the description covers the outcome of each verdict and the conditional parameter requirement. The main gap is the unexplained Evidence object and as_agent parameter, which an agent would still need to infer.

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 0% with 5 params, so the description must compensate. It adds real meaning for Verdict (enumerates the three allowed values the schema does not) and CommitHash (required only on fix_confirmed), but Evidence (a nested object), as_agent, and AttemptId are left entirely unexplained.

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

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

States a specific verb+resource ('the fix-verifier's verdict on a fixer's attempt') and situates it in the audit plan workflow, so the agent knows this is submitting a verifier judgement, not a fix or a review decision. It does not explicitly name how it differs from siblings like submit_verification_verdict or submit_review_decision, but the role phrasing is specific enough to distinguish it.

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

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

Gives clear conditional context: which verdict value yields which outcome (fix_confirmed→fixed, fix_failed below retry cap→still claimable, partial→child finding). This tells the agent when each verdict applies and what state results. It stops short of naming alternatives or prerequisites (e.g., who may call it, when it is invalid).

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 and does well: it discloses the state-machine consequences of both branches (empty list → done, non-empty → review) and that findings are created in pending_verification. It omits whether the claim is consumed/released and any error behavior for an invalid ClaimToken.

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

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

Three tight sentences, front-loaded with the scope restriction and then the two branch outcomes. No filler, each sentence adds a distinct behavioral fact.

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

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

No output schema and no annotations, yet the description covers the important outcome of both branches, which is what an agent needs to invoke this correctly. It leaves a gap on finding payload structure and ClaimToken handling, so not fully complete for a 3-param mutation.

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 0%, so the description must compensate. It alludes to one parameter (the findings list, and implicitly the claimed task for ClaimToken) but never explains the shape of a finding, the format or role of ClaimToken, or what as_agent does.

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

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

States a specific verb+resource ('submit findings') scoped explicitly to 'the currently-claimed task' and to 'Audit-plan only', which separates it from sibling submit_* tools like submit_verification_verdict and submit_attempt_verdict. An agent can identify what it does and when it applies without opening the schema.

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

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

The 'Audit-plan only' scope and 'currently-claimed task' precondition give clear context for when this applies versus other lifecycle submits. It does not name an alternative tool or state when-not to use it, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden and does well: it discloses the state machine (approved → done, changes_requested → pending or needs_human_review at retry cap) and the side effect that commit_hash is recorded on the latest attempt. It does not cover permissions, the actual retry-cap value, or return 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?

It is compact and front-loaded, stating the purpose first then the branch consequences in a single dense passage with no wasted sentences. Density is high but every clause conveys actionable state-transition 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 mutation tool with no annotations and no output schema, the state-transition coverage is solid, but gaps remain: the retry cap value is unspecified, as_agent semantics are unaddressed, and there is no indication of the response. Adequate but not fully complete given the tool's complexity.

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 0%, so the description must compensate, and it partially does: it documents the Decision enum values and explains CommitHash's conditional effect. However TaskId, Comments, and notably as_agent (which likely controls identity/auth context) are left entirely unexplained.

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

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

The description opens with a specific verb+resource ('a reviewer's verdict on a task in review'), which cleanly separates it from sibling verdict tools like submit_verification_verdict and submit_attempt_verdict that operate on findings/attempts rather than tasks. It never explicitly names those siblings, so differentiation is by inference rather than direct routing guidance.

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

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

It clearly states the conditions and consequences for each decision branch (approved moves to done; changes_requested returns to pending or escalates at cap), which tells an agent when each value is appropriate. It stops short of naming alternative tools or stating prerequisites, so it is clear context without explicit 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 usefully discloses the side effects — evidence is written to the verdicts table and the finding status transitions — but is silent on permissions, whether a verdict can be resubmitted or overridden, and what happens if the finding is not in a pending-verification state.

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

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

Three tight sentences with the audit-plan scope front-loaded and no filler. It could be marginally tightened, but every clause carries 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 mutation tool with no annotations and no output schema, the description covers the outcome side reasonably but omits the claim prerequisite, the meaning of ClaimToken, as_agent semantics, and error/retry behavior. An agent could invoke it but would likely guess at how to obtain a valid ClaimToken.

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 0%, so the description must compensate. It supplies the allowed verdict values (confirmed, rejected, ambiguous) — which the schema itself lacks — and example Evidence keys, but leaves the required ClaimToken completely unexplained and adds nothing about as_agent. Half the parameters, including the only required one, remain undocumented anywhere.

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?

Specific verb (submit) plus resource (the verifier's verdict on a pending-verification finding), and the 'Audit-plan only' prefix scopes it well. It does not explicitly distinguish itself from close siblings like submit_attempt_verdict, submit_review_decision, or override_verdict, so an agent must infer the difference from the finding-state wording.

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 'Audit-plan only' constraint and 'pending-verification finding' precondition imply when the tool applies, but no alternatives are named and no explicit when-not guidance is given. Critically, it never says the finding must first be claimed via claim_next_finding_for_verification, which the sibling list suggests is a prerequisite.

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