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

Annotations already declare readOnly=false, destructive=false, idempotent=true, openWorld=false, so the safety profile is known; the description usefully adds the hidden side effects (board-sync items enqueued per task, a plan.activated Slack post). It leaves one real gap: with idempotentHint=true, it does not say whether those side effects fire again on a repeated call.

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 zero filler; the admin/permission signal and the state transition are front-loaded, and the side-effect sentence follows in priority order.

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

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

For a two-parameter mutation with no output schema, the description covers what it does and its externally visible effects well. The omissions are the undisclosed 'as_agent' parameter and any indication of what a successful activation returns.

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 clarifies neither parameter. PlanId format/constraints are unstated, and 'as_agent' — a governance-relevant impersonation field on an admin mutation — is not mentioned at all, so the description fails to compensate for the empty schema.

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

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

States a specific verb and resource plus the exact state transition ('move a plan from draft to active'), which no sibling tool performs. An agent can distinguish it from create_plan, archive_plan, and export_plan 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?

The 'Admin:' prefix signals a permission prerequisite and the draft→active transition implies the precondition, but the description never names an alternative (e.g., archive_plan for retirement) or says when not to use it. Usage 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the description's contribution should be the extra context: what a second identical call does, how OrderIndex collisions are resolved, and whether rename/duplicate Name values are rejected. It provides only the 'Admin:' permission hint and says nothing about these ordering/idempotency behaviors, which matter most for a non-idempotent mutation.

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

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

Two tight sentences, front-loaded with the admin action, and the second sentence adds genuine domain context rather than padding. Nothing is wasted, though the space saved could have been spent on parameter semantics.

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 non-idempotent mutation with no output schema and zero documented parameters, an agent cannot determine valid OrderIndex values, Name constraints, failure modes, or what is returned. The description covers the concept of a phase but not enough to invoke the tool correctly without guessing at the required fields.

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

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

Schema description coverage is 0% for all four parameters, so the description carries the full burden — yet it names none of them. Crucially, the required 'OrderIndex' is left completely unexplained (its range, whether gaps are permitted, how it interacts with sibling phases), and 'as_agent' and 'Name' get no mention at all.

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') so the operation is unambiguous. It also clarifies the domain concept ('phases are an optional structural layer; tasks may be unphased'), which separates it from task-creation siblings like create_task, though it never names an alternative tool.

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

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

The 'Admin:' prefix signals a privileged operation, and the note that phases are optional implies this is not always required. But there is no explicit when-to-use/when-not guidance, no prerequisites (does the plan need to be in a particular state?), and no named alternative for restructuring an existing plan.

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

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

Annotations already declare that this mutates state, is non-idempotent, and is not open-world, so safety is covered. The description adds useful sequencing context (the Status option ids must pre-exist), but says nothing about duplicate-registration behavior, permission requirements, or what a failure looks like — relevant given idempotentHint=false.

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 compact sentences, with the core action front-loaded after the 'Admin:' prefix. The parenthetical about the discover endpoint is slightly vague but not wasteful.

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 write tool with no output schema and no parameter descriptions, the description is thin. An agent still cannot tell which optional fields are needed for a minimally valid call or how the various node-id fields relate to one another.

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, so the description carries the full documentation burden and mostly does not meet it. It only indirectly explains the five StatusOption*/StatusFieldNodeId fields as GraphQL-discovered ids; ProjectId, GithubOwner, DisplayName, GithubProjectNumber, GithubProjectV2NodeId, and as_agent are 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?

States a specific verb and resource ('register a GitHub Projects V2 board for a project') and flags the admin scope, which separates it from sibling helpers like add_project_repo or create_project. It doesn't compare itself to those siblings explicitly, but the resource 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?

Gives a clear precondition for use: the caller must have already discovered Status field option ids via the GraphQL API, and it points at a discover endpoint as the way to do that. It stops short of saying what to do if the board is already registered or when not to call it.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds real value by disclosing the admin requirement and the important consequence that reference-only repos are left untouched, but it is silent on duplicate-attach behavior (relevant given idempotentHint=false) and on what a successful call returns.

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

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

Two short sentences, zero waste, with the privileged nature and the core action front-loaded before the reference-only nuance. Nothing is repeated or padded.

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 five-parameter mutation tool with no output schema and no parameter documentation, the description does far too little: it omits the required ProjectId, the repo identifier format, the role of as_agent, and failure modes. An agent could not confidently construct a call from this text alone.

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 five parameters, and the description only illuminates one of them indirectly (IsReferenceOnly, via the "not modified by the system" sentence). It never clarifies whether GithubRepo is a bare name or owner/name path, why GithubOwner is separate, or what as_agent does, leaving genuinely ambiguous inputs.

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") and the "Admin:" prefix signals the privileged nature of the operation. It is clearly distinguishable from siblings like add_project_board or set_project_slack, though it never names those alternatives 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?

The "Admin:" label implies when the tool is applicable (administrative setup of a project) and the reference-only sentence hints at the design-time vs delivery-time distinction. But there is no explicit when-to-use/when-not guidance or comparison with the other project-configuration 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?

Annotations only flag destructive/idempotent; the description goes far beyond by naming the required permission (can_archive_plan), enumerating exactly which tools reject an archived plan and with which structured error (plan_archived), stating irreversibility, and confirming tasks/events/board cards survive for forensics. It also discloses the side effect of posting a plan.archived Slack notice and the returned fields, none of which is in the annotations.

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

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

The core action and permission requirement are front-loaded, and nearly every sentence adds operational value (blocked tools, error code, idempotency, side effects). It is a dense single block though; the return-value and outcome detail could be split or trimmed without loss.

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 destructive, permission-gated mutation the description covers effects, reversibility, idempotency, side effects, and return values (no output schema exists, so this matters). The only real gap is the undocumented `as_agent` parameter, which an agent may need 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?

With 0% schema coverage the description must carry parameter meaning, and it does for Outcome ('Completed' default or 'Canceled', suffixing the audit milestone title and appearing on Slack) and Reason (shown on the Slack notice); PlanId is self-evident. However, the fourth parameter `as_agent` is never explained, leaving one of four parameters 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?

The description opens with a specific verb and resource — 'Archive (disable) a plan so it stops accepting work' — and immediately clarifies the semantic effect (disable, not delete). It is clearly distinguishable from siblings like activate_plan and create_plan, which it mentions by name in the effect list.

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

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

It states exactly when to reach for this tool ('retire a finished or abandoned plan') and explains the downstream lifecycle consequence: the next orchestrator bootstrap finds no active plan and creates a fresh one, which is how a new pass is started on demand. It also gives the key when-not signal implicitly and explicitly via the one-way, no-un-archive constraint, so an agent knows there is no undo path.

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?

Goes well past annotations by explaining the actual mechanism: a cancel request is queued on the audit-dispatch outbox, a background worker signals the session, and the orchestrator's own /audit-cancel cleanup runs ('no hard kill'). It also discloses the response shape (per-project status of 'queued' or 'unknown_project'), which is exactly the kind of context annotations cannot convey.

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 action and scope, then the mechanism, then the result format. Four sentences all carrying information; the outbox/worker sentence is dense but earns its length by explaining the non-destructive semantics.

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, the description usefully explains the returned per-project statuses, and the async cancel mechanism is fully described. The only real gap is the undocumented `as_agent` parameter and the ambiguity around whether `projects` is mandatory.

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 does well for `projects` — accepting a list of slugs or ids and noting each is resolved. However, `as_agent` is never mentioned, and the schema marks no parameters required while the description implies `projects` must be passed.

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 the 'Admin:' prefix signals the privilege class. It is trivially distinguishable from request_audit and the other lifecycle 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 framing and 'cancel a running audit' imply the situation, but there is no explicit when-to-use/when-not, no mention of what happens if the audit is not running, and no named alternative. 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?

Annotations already declare the safety profile (not read-only, not idempotent, not destructive), and the description adds that the tool is reserved and unnecessary in v1. However, it does not state what happens if the tool is called now (no-op, error, or future behavior), leaving a behavioral gap.

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

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

Two concise sentences with the key constraint stated first. There is no wasted text.

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

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

For a reserved tool with no output schema, the description sufficiently explains why it should not be used in v1. However, it omits parameter meaning and what calling the tool would actually do, which are relevant gaps even for a placeholder.

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 does not explain PlanId or as_agent at all. Parameter names offer minimal meaning, but the description fails to compensate for the missing schema documentation.

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

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

The description clearly states that this is a reserved tool surface for a future queue and that it is not needed in v1. It distinguishes itself from the verdict siblings by explaining that they accept the attempt id directly, though it does not describe an actionable purpose because none currently exists.

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

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

It explicitly says no separate claim is needed in v1 and names the alternatives (submit_attempt_verdict and submit_review_decision) that use the attempt id from orchestrator working state. This gives the agent a clear condition for avoiding 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?

Annotations only cover the safety triad; the description adds two things they don't: the claim mutates state by setting the finding to in_fix, and the caller implicitly becomes the fixer. It omits what happens when no eligible finding exists and whether the claim has a lease/expiry (refresh_claim and release_claim in the sibling list suggest one exists).

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 plan-scope constraint and the selection rule front-loaded before the side-effect disclosure. No filler, though 'below-cap fix_failed/partial' is compressed to the point of ambiguity.

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

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

Given no output schema and a mutation tool with two undocumented parameters, key facts are missing: the return payload (does it return the finding or just a confirmation?), behavior when no claimable finding exists, the meaning of 'below-cap', and any claim lease/TTL. A claim tool that silently changes status needs at least the failure mode documented.

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 carry the parameter burden and does not. PlanId is only obliquely implied by 'Audit-plan-only', and as_agent is never mentioned at all — notably it appears to conflict with 'Caller is implicitly the fixer', leaving the agent unsure how to attribute the claim.

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), the exact resource (a finding), and the selection rule (highest-severity confirmed, or below-cap fix_failed/partial). The 'for_fix' scope plus the selection predicate clearly separates it from claim_next_finding_for_verification.

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' sets the applicability constraint up front and 'to fix' implies the alternative (verification) is a different tool. It never explicitly names claim_specific_task or claim_next_finding_for_verification as the alternatives, so routing is inferred from names 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?

The description discloses behavior the annotations don't cover: the calling actor is implicitly assigned the 'verifier' role for the claim duration, and the empty-queue return is named. Annotations only give the mutation safety profile, so this added context is valuable. It stops short of explaining claim release/expiry.

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, scope front-loaded, no filler. Every clause conveys distinct, useful information.

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

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

For a non-readonly claim mutation with no output schema, the description covers role assignment and the empty-queue case, but leaves the as_agent parameter and the claim lifecycle (expiry, release) unexplained, which an agent needs 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 document both parameters. It implies PlanId via 'on the plan' but says nothing about 'as_agent', leaving half the 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 (claim) and resource (highest-severity pending-verification finding) scoped to the audit plan. The 'verification' qualifier distinguishes it from siblings like claim_next_finding_for_fix and claim_next_attempt_for_review, though it doesn't explicitly 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?

'Audit-plan-only' sets a clear precondition, and 'Returns no_work_available if no findings are waiting' tells the agent what to expect when the queue is empty. It lacks an explicit pointer to the alternative claim tools, keeping it 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?

Annotations declare non-read-only, non-idempotent, non-destructive, but the description adds genuinely new behavior: the operation is atomic, it returns { task, claim_token } or no_work_available, and it has the side effect of assigning the bound Project V2 card to the calling actor's GitHub user. The claim TTL/expiry behavior implied by TtlOverride is left unexplained.

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

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

Four sentences, front-loaded with the action and selection rule, followed by validity constraint, return contract, usage trigger, and side effect. No filler and each sentence adds 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?

For a mutating claim tool with no output schema, the description supplies the return contract, atomicity, and the GitHub card side effect — more than most. Gaps remain around claim lifetime/TTL semantics and the enumerated valid roles per plan_type, which matter 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 coverage is 0%, so the description must carry parameter meaning. It does well for Role ('must be valid for the plan's plan_type', with examples) and implies PlanId's role, but as_agent and TtlOverride — two of four parameters — are never explained, leaving their semantics 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?

States a specific verb and resource ('claim the highest-priority pending task on a plan') plus the selection rule, which separates it from claim_specific_task without naming that sibling. The role/plan_type coupling is also concrete. It stops short of explicitly naming the neighboring claim tools, so an agent must infer the boundary.

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 clear positive trigger, implicitly contrasting with picking a specific task. No explicit when-not-to-use or pointer to claim_specific_task, 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?

Adds real context beyond the annotations: the failure mode 'task_unavailable' when another actor holds an unexpired claim, and the side effect of assigning the Project V2 card to the caller's GitHub user. It does not explain TTL expiry semantics or what Role/as_agent change behaviorally, leaving some gaps for a non-idempotent 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?

Three compact sentences with the action front-loaded, followed by failure mode and side effect. No filler, though the side-effect sentence 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?

Covers the error condition and mutation side effect for a non-idempotent write with no output schema, which is the minimum an agent needs. However, with three of four parameters undocumented, an agent lacks enough to invoke meaningfully in non-default cases.

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 carry parameter meaning, but it only clarifies TaskId ('by id'). Role, as_agent, and TtlOverride are completely undocumented in both schema and description, leaving an agent guessing at 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?

States a specific verb and resource ('Claim a specific task by id') and implicitly distinguishes itself from the sibling claim_next_task by being targeted at a caller-chosen id. Also names the side effect of assigning the bound Project V2 card.

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 says 'Use when the orchestrator is directing work (e.g. dispatching a subagent to a particular task)', giving a concrete selection condition. It stops short of naming claim_next_task as the alternative for the pull-based case, but the context makes the split inferable.

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

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

Annotations already establish that this is a non-read-only, non-destructive creation operation. The description adds important context beyond annotations: admin scope, draft status, automatic board inheritance, board-sync side effects, the null PrimaryBoardId meaning, and the activate_plan follow-up.

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

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

The description is front-loaded with the core action and status, then proceeds directly into the critical board-binding behavior and the activation follow-up. Every sentence adds meaningful invocation or follow-up context, with no redundant 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, but the description compensates by explaining the echoed resolved PrimaryBoardId and what null means. It also covers the key board-sync behavior and next step; the remaining gap is the unexplained optional 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?

The description explains PrimaryBoardId in depth, including inheritance rules and response semantics. However, schema description coverage is 0% and six of seven parameters are not explained, including non-obvious fields such as PlanType, as_agent, and PrimarySlackChannelId.

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

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

The description states a specific verb and resource ('create a new plan') plus initial status ('in draft status'). It also differentiates the follow-up path by naming 'activate_plan', so an agent can distinguish creation from activation without opening other 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?

It gives explicit conditional guidance for PrimaryBoardId: omit it when the project has exactly one registered board, pass it explicitly only when the project has more than one board. It also routes the agent to activate_plan for moving the plan to active and enqueueing board items.

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

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

Annotations already declare this a non-read-only, non-destructive, non-idempotent write, so the description's job is lighter. The 'Admin:' prefix adds an auth requirement not covered by annotations, and the slug note hints at the identifier's downstream role, but it says nothing about duplicate-slug handling, side effects, or what is returned.

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

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

Two short sentences, front-loaded with the action and the most consequential parameter semantics. 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 mutating admin tool with four optional parameters, no output schema, and no annotation coverage of auth, the description leaves too much open: the 'as_agent' parameter, slug derivation, duplicate behavior, and what the call returns are all unstated.

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 carry parameter meaning, yet it only explains Slug ('stable identifier used in URLs and CLIs'). DisplayName and Description are self-evident, but 'as_agent' is completely opaque, and nothing says whether slug is generated or required despite zero required params.

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

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

The description states a specific verb and resource ('create a new project') and adds the 'Admin' scope marker. It is clear on its own, but it does not differentiate itself from siblings such as create_task or create_plan beyond the resource name.

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 permission/role prerequisite, which is the only usage signal given. There is no statement of when to use this versus alternatives, no prerequisites for slug availability, and no note about what to do if the project already 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?

Goes well beyond the annotations: states the created status (pending), dependency semantics including cycle rejection at insert and the same-plan constraint, and the always-on board sync that makes BoardSyncWorker create a draft GitHub Projects V2 item in Backlog on first drain. It also discloses that Slack is opt-in with notify_slack defaulting to false, which is exactly the kind of side-effect detail an agent cannot infer from readOnlyHint/destructiveHint.

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 initial state, and each sentence contributes new information (dependencies, board sync, Slack). It is dense and slightly run-on in places, but nothing is 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?

Strong on dependencies and side effects for a mutation tool with no output schema, but an agent still cannot tell what most of the 11 inputs mean or what the call returns (the created task id, presumably, but unstated). With 0% schema coverage the description should have closed more of that 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% across 11 parameters, so the description carries the full burden — yet it explains only DependsOn and NotifySlack. Title, PlanId, PhaseId, Priority, Paths, as_agent, Description, ExternalKey and ReferencePointer get no semantics at all, and the casing mismatch ('depends_on' / 'notify_slack' vs DependsOn / NotifySlack) is unaddressed.

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?

Opens with a specific verb, resource and initial state: 'Create a new task on a plan, in pending status.' That is far more precise than the name alone. It never distinguishes itself from the sibling 'create_tasks' (bulk variant), which is the one confusion an agent is likely to have.

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 caller context: 'Used by orchestrators that decompose larger work units into tasks at runtime, and by admin tools that import work from external sources.' It also explains downstream consumption via claim_next_task / claim_specific_task, which helps an agent reason about sequencing. It stops short of explicit exclusions or pointing at 'create_tasks' for bulk creation.

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?

Goes far beyond the annotations: discloses the two-pass insert-then-wire algorithm, cycle rejection behaviour, and the crucial non-atomic detail that 'rolls back nothing (already-inserted tasks remain)', plus the board-sync side effect and Slack opt-in default. For a mutation tool with only generic hints, this is exactly the operational context an agent needs before committing a batch.

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

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

Dense and front-loaded — the batch scope comes first, then mechanics, then side effects, then the Slack toggle. Some sentences pack multiple claims (the cycle sentence chains rejection, non-rollback, and retry strategy), which rewards careful reading but costs little.

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 failure modes, persistence semantics, side effects and the Slack default, which is strong for a non-atomic mutation with no output schema. The remaining gaps are the undocumented as_agent parameter and no statement of what the successful response contains (counts, ids, cycle payload).

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?

With 0% schema coverage the description carries the full burden and does most of it: it defines the item-level fields external_key, depends_on_ids and depends_on_external_keys and explains NotifySlack's default and effect. It leaves 'as_agent' entirely unexplained and the Tasks array's own element shape is never spelled out beyond the dependency keys, so it stops short of complete.

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 — 'Bulk task creation' — plus the scope 'a list of tasks on a single plan', which cleanly separates it from the singular create_task sibling. An agent knows immediately this is the batch path rather than the one-at-a-time 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?

Usage context is present but incidental: 'for orchestrator bootstrap (e.g. Phase 0 of an audit)' and the conditional 'pass true if you want every task announced'. It never explicitly compares against create_task or says when a single-task call is preferable, so the selection decision is implied rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false; the description adds value beyond them by disclosing determinism, one-way semantics, and that the markdown copy is not authoritative. It doesn't cover auth requirements or whether as_agent changes permissions/visibility.

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 purpose, then format options, then the one-way caveat. Nothing is padding; each sentence adds a distinct 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, but the description characterizes the JSON return ('full structured tree of tasks, findings, attempts, verdicts') and markdown's human-readable stability. Only the as_agent parameter remains unexplained, which is a modest gap for a low-complexity read 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%, so the description must compensate. It does explain Format's allowed values (markdown, json) - information notably absent from the schema - but PlanId is unstated and as_agent is completely 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: export a deterministic snapshot of a plan. It adds scope ('deterministic snapshot') and intended destinations (repo, chat) so the agent can distinguish it from read tools like get_plan_dashboard or list_plans 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?

Gives concrete use contexts (committing to a repo, pasting into chat) and clarifies the direction of the operation ('export is one-way - the database is the source of truth'). No sibling is named as an alternative, but no sibling performs export, so the routing gap is minor.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the events table records every state change with actor and reason, which is useful context, but says nothing about result volume, ordering, or pagination despite a Limit parameter existing.

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 filler, with the primary purpose front-loaded and the investigative use case as supporting detail. Slightly compact relative to the tool's complexity, but nothing is wasted.

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

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

With five parameters, a nested object, and no output schema, the description should clarify what a caller gets back and how Since/Limit shape the result. It partially gestures at the return content (events with actor and reason) but leaves the parameter mechanics unexplained.

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 five parameters, one of which (Since) is a nested object. The description only hints at EntityType via the entity-kind list; it says nothing about EntityId, Limit, Since, or as_agent, so it fails to compensate for the documentation 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 (forensic event log for a specific entity) and enumerates the entity kinds it covers (task / finding / attempt / plan / phase). The purpose is unambiguous, though it does not name any sibling tool to distinguish itself from.

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 triggering scenario: investigating 'why did this task end up in needs_human_review'. That is a clear usage context, but there is no guidance on when not to use it and no reference to adjacent tools such as get_stuck_work.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds material context beyond them: no claim or ownership is required, recovery works after a restart or for an orchestrator that did not author the findings, unknown ids produce a structured not_found error, and the live claim token is deliberately withheld. These are exactly the behavioral facts an agent needs before deciding to call 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?

Front-loaded with what is returned, then routing guidance, then caveats; every sentence carries information. The field enumeration is long but serves to tell the agent whether the payload is sufficient, though the sentence could be tightened slightly.

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, the description compensates by enumerating the returned body fields and the error case. It omits any explanation of the as_agent parameter, which is the only notable completeness gap for a simple two-parameter read 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%, so the description must carry the burden. It clarifies FindingId semantics implicitly ('by id') and that unknown ids trigger not_found, but the second parameter as_agent is never mentioned or explained in either the schema or the description, leaving a real 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 ('Retrieve the full body of a single finding by id') and enumerates the fields returned, so the agent knows exactly what it gets. It explicitly contrasts with claim_next_finding_for_verification and claim_next_finding_for_fix, which return only a stub, making selection 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?

Gives an explicit trigger: after a claim tool returns only id/task/status/severity, call this to fetch the auditor-authored body needed to reproduce the issue. It also states a when-not/alternative condition indirectly ('No claim is required: this is a plain read') and directs the agent to a claim tool when a live claim token is needed.

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

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

Annotations already establish readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine context beyond them: that the scope spans every plan and covers three claim categories, and that the intended behavior is state recovery after a restart. It does not say what the claims look like on return or whether the caller must re-acquire/refresh them afterward.

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: the first defines the returned content, the second defines the use case. Front-loaded with the payload scope and 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 zero-required-parameter read tool with no output schema, the description covers what is returned and why. The remaining gap is the undocumented as_agent override, plus no hint about whether returned claims include the IDs needed to release or refresh them.

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

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

Schema coverage is 0%, so the description carries the full burden for as_agent, yet the parameter is never mentioned. The phrase 'the calling actor' implies an implicit identity, but an agent cannot tell whether as_agent overrides that identity, what format it expects, or why it would be set.

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 retrieval: 'Every active claim the calling actor currently holds across every plan,' and enumerates exactly which claim types are returned (tasks, findings, attempts in review). This cleanly distinguishes it from the sibling claim_next_* and get_stuck_work tools, which acquire or diagnose rather than enumerate the caller's own holdings.

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 this on session start to recover claims after a Claude restart.' That is a clear when-to-use signal an agent can act on. It stops short of naming alternatives (e.g., get_stuck_work or refresh_claim) or stating when this tool is not 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: it discloses in-process caching for 5 seconds and invalidation via LISTEN/NOTIFY, which is real staleness information an agent cannot get from annotations. It does not mention the caller-identity behavior of `as_agent`, which is the one behavioral gap.

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, front-loaded with the payload inventory, then the orchestration use case, then caching semantics. No filler and nothing repeated from annotations or schema.

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

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

With no output schema, the description correctly enumerates return contents and their bounds (up to 5 tasks, 20 events), which is exactly what an agent needs to plan around. The remaining hole is `as_agent` semantics and what the stuck-work threshold means operationally for any non-default caller identity.

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 two parameters, so the description must compensate — and it does not. `PlanId` is inferable from context, but `as_agent` is a semantically loaded parameter (whose claims are reported as 'the caller's'?) that 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+resource ('Comprehensive snapshot for one plan') and enumerates exactly what the snapshot contains (per-status counts, per-phase counts, next-claimable tasks, held claims, stuck work, recent events). This sharply distinguishes it from siblings like get_stuck_work, get_event_log, and get_my_active_work, which each return a subset.

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 clear usage context and implicitly tells the agent to prefer this over assembling the picture from the narrower sibling tools. It stops short of explicitly naming those alternatives or stating when NOT to use it (e.g., when only recent events are needed, use get_event_log).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds real value beyond that by defining the exact semantics of 'stuck' (five concrete detection rules) and noting the data mirrors an hourly batch job, so an agent knows it is a read-only reconstruction rather than fresh state mutation. It does not mention cost or result size for a global scan.

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

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

One front-loaded sentence that names the mechanism, then a compact enumeration of the detection categories, then the scoping clause. No filler and no repetition of the tool name or annotations.

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 0% parameter coverage, the description does its job of explaining what kinds of records come back, but an agent still cannot tell what 'as_agent' does or whether the response is grouped per category. Adequate for the return-content question, incomplete for invocation details.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. 'Scoped to a single plan or global' implicitly explains PlanId (omit it for global), but 'as_agent' is never mentioned at all, leaving a likely impersonation/identity parameter completely undefined 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+resource ('on-demand view of ... stuck-work') and enumerates the five detection categories (TTL-expired tasks, over-long claims, stale pending_verification findings, expired attempts, silent plans), which tells an agent exactly what data it returns. It does not, however, distinguish itself from near-neighbors like get_plan_dashboard or get_my_active_work, which also surface work state.

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?

'Scoped to a single plan or global' implies the two usage modes, and 'on-demand view of the same data the hourly job computes' implies it is for checking current state without waiting for the hourly job. But there is no explicit guidance on when to prefer this over get_plan_dashboard / get_my_active_work, and no prerequisites or exclusions are given.

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

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

The annotations already establish that this is a safe, idempotent read. The description adds useful behavioral context about the return payload: each plan includes per-status task counts, which reduces extra dashboard calls. It omits ordering, pagination, or auth details, but adds real value beyond the annotations.

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

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

Two sentences, front-loaded with the core action and followed by the practical benefit. 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 read-only list tool with no output schema, the description adequately explains the key returned data and why it matters. The main gap is the undocumented 'as_agent' parameter, though the core behavior is otherwise clear.

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

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

Schema description coverage is 0%, so the description must explain all three parameters. It covers ProjectId and Status at a high level, but 'as_agent' is never mentioned, and there is no detail about valid status values or how filtering works.

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 ('List plans on a project') plus optional filtering by status. It also distinguishes the tool's value from dashboard calls, so an agent can identify its role among siblings such as get_plan_dashboard and list_projects.

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 a clear use case: pick the next plan with workable work by using embedded per-status task counts instead of making N additional dashboard calls. It lacks explicit when-not-to-use guidance, but the alternative behavior is strongly implied.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context by explaining visibility scoping ('calling actor can see') and the returned aggregates, though it omits any mention of permissions, rate limits, or pagination.

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

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

The description is two sentences, front-loaded with the core action and scope, followed by a clear usage cue. No sentence is wasted.

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

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

For a simple read-only list tool with no required parameters and no output schema, the description does well by describing the returned per-project data and the wake-up use case. The only notable 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?

There is one optional parameter, 'as_agent', with 0% schema description coverage, and the description does not explain it at all. The phrase 'calling actor' hints at actor selection but does not clarify what 'as_agent' does or when to supply it.

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

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

The description states a specific verb and resource ('List every project') and clarifies the scope ('the calling actor can see') plus the aggregate data returned. This clearly distinguishes it from sibling tools like list_plans and 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?

It gives a clear usage context: 'Use this as the first call when a developer or orchestrator wakes up and needs to decide what to work on.' It does not explicitly state when not to use it or name alternatives, but the intended situation is unambiguous.

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

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

Although annotations already declare non-readonly, destructive, idempotent, and closed-world behavior, the description adds important operational context: it bypasses the claim mechanism, specifies exact permission flags for status groups, and discloses board and Slack side effects with reason propagation.

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

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

The description is front-loaded with purpose and valid statuses, then adds permission and side-effect details. Despite being dense, every clause contributes operational information and 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 destructive, permission-gated mutation with side effects, the description covers statuses, override behavior, permission requirements, and board/Slack effects. The main gap is that as_agent is not explained, and there is no mention of return or error behavior beyond the 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 description coverage is 0%, so the description carries the burden. It compensates by listing allowed Status values and implying Reason is the supplied reason, but it omits any explanation of as_agent and gives no format or semantics beyond the status enumeration.

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: setting a task to a non-normal status. It enumerates the exact statuses and distinguishes this from normal task flow by noting it bypasses the claim mechanism via the override 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?

It gives clear usage context: non-normal statuses, an override path, and permission requirements per status group. However, it does not explicitly name alternatives such as override_verdict or release_claim, nor does it state when not to use 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?

Annotations already flag destructive=true and idempotent=true, but the description adds information they cannot carry: the required can_override_verdict permission, that an override event is written with the supplied reason, and that tasks trigger board plus Slack side effects on the bound Project V2 card and channel. Those side effects are the most important thing an agent needs to know before calling a destructive tool, and they are stated plainly.

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 action and the hard constraint, then permissions, then side effects, then routing. Every sentence carries content, though the attempts/record_commit clause is dense enough to require a second read.

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 destructive, side-effecting mutation with an undocumented schema and no output schema, the description covers permissions and side effects well but leaves critical gaps: what status values NewStatus accepts, what happens to a live claim if one exists, and what the caller gets back after the override event is written.

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 5 parameters with no enums, so the description bears the full burden — yet it only glosses Reason ("the supplied reason") and hints that EntityType distinguishes task/finding/attempt. NewStatus gets no valid-value guidance despite driving the whole operation, as_agent is never mentioned, and EntityId's required-ness and expected ID format are unaddressed.

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 — force a state change on a task or finding — plus the defining constraint (without holding its claim), which is exactly what separates it from mark_task_status and the submit_* siblings. An agent can tell what this does and where it sits in the workflow 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?

Gives an explicit trigger case (a subagent's claim went stale but the work produced still needs recording, e.g. a verifier that finished after TTL), and routes two related cases away: attempts go to record_commit, and verdicts must be overridden on the parent finding. That is when-to-use, when-not, and named alternatives in one paragraph.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description usefully discloses the emitted event, but does not warn what happens on repeat calls despite idempotentHint=false, nor whether any claim/workflow state changes.

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 action, then the effect, then the routing condition. 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 with no output schema and 0% parameter coverage, the description covers the what/why but omits the remaining field semantics and duplicate-record behavior an agent would need to call it reliably.

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 carry weight: it conveys EntityId/EntityType semantics (task, finding, or attempt) and the meaning of CommitHash. It says nothing about RepoId, TargetBranch, or as_agent, leaving half the parameters 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?

States a specific verb and resource — attach a commit hash to a task, finding, or attempt — and immediately follows with the side effect ('Writes a commit_recorded event'). This clearly separates it from submit_attempt, which is the normal path for commit association.

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 scopes usage: 'Use when the commit happens outside the normal submit_attempt flow (e.g. a hotfix going in via override).' It names the alternative sibling and the condition that selects this tool over it, leaving nothing 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?

Goes well beyond the annotations: it discloses the authorization precondition (token must be live AND held by the calling actor), the sweeper race that makes expired refreshes unsafe, the side effect of writing a claim_refreshed event, and the plan-level refresh limits with the exact refusal shape (claim_limit_reached, details.reason of max_lifetime or no_progress, claimed_until). That is exactly the behavioral context annotations cannot carry.

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 purpose and trigger, then escalates to preconditions, side effects, and error contract. Dense but almost every sentence adds new information; the parenthetical about the verifier mid-deploy is illustrative rather than essential, keeping it just short of a 5.

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 compensates by describing both the success side effect (claim_refreshed event) and the failure contract (error code, details.reason values, claimed_until). Nothing an agent needs to call this correctly or handle refusal 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 description coverage is 0%, so the description must carry the load; it does for ExtendBy (duration shorthand like '30m'/'2h', default = role's configured TTL added to claimed_until) and for ClaimToken (must be live and actor-held). The 'as_agent' parameter is never explained, which leaves one of three parameters undocumented — the only real 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 plus the key differentiator: 'Extend an active claim's TTL without releasing it.' That phrase alone separates it from release_claim and the claim_* siblings, so an agent can select it 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?

Gives an explicit trigger ('when a subagent's reproduction is taking longer than the configured role TTL') with a concrete example, and an explicit exclusion ('an already-expired claim cannot be reanimated here — it must release and re-claim'). Both when-to-use and when-not-to-use are stated, plus the alternative path.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, yet the description adds real context beyond them: status reverts to pending, the card moves to Backlog and is lazily created if absent, assignees are cleared for the next claimer, and Slack is deliberately skipped. That last point preempts a natural agent question about notifications.

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 in the first clause, side effects follow, and the Slack note closes as a plausible agent question. No obvious filler, though the parenthetical about lazy card creation is dense and slightly interrupts the flow.

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 with no output schema, the description covers what changes in the system, which is the main thing an agent needs. The gaps are the undocumented parameters and no statement of what a successful call returns or what happens if the token is stale.

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 says nothing about the three parameters – not ClaimToken's role, not the optional Reason, not as_agent. With low structured coverage the description was expected to compensate, and it does not, leaving an agent to infer how Reason is surfaced.

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?

"Release a claim without submitting work" names a specific verb and resource and immediately draws the line against the submit_* siblings. The follow-on sentence spells out the resulting state transitions, so an agent knows exactly what this operation does to the task, board card and assignees.

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 a clear triggering condition: the agent has decided it cannot complete the work and wants to return it to the pool. The contrast with submitting is stated explicitly. However, no sibling is named by name (e.g. submit_findings, submit_attempt) and no exclusion such as "if you can partially complete, submit instead" is given, so it stops 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?

Beyond the annotations (which only say non-read-only, non-idempotent, open-world), it discloses the asynchronous dispatch mechanism, that a background worker launches the orchestrator, that the caller performs no repo checkout, and the exact per-project outcome statuses including 'unknown_project'. This is materially useful behavioral context for a fire-and-forget dispatch 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?

Front-loaded with the action, then parameter semantics, then mechanism, then return shape — a logical order with no filler sentences. It runs a bit long in one block and the parenthetical about SSH/watch commands could be trimmed, but every sentence 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?

With no output schema, the description does the right thing by spelling out the per-project result shape ('queued' with dispatch id and attach_command, or 'unknown_project'). Gaps remain: `as_agent` is undocumented and the text says 'one or more projects' while the schema marks no parameters as required, leaving an ambiguity an agent must guess at.

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 compensates for only one of two parameters, clarifying that `projects` is a list of project slugs or ids (the bare schema gives an untyped array). The `as_agent` parameter is never mentioned anywhere, leaving its meaning and permission implications 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?

The description names a specific verb and resource ('request a full audit run'), scopes it ('for one or more projects'), and describes the resulting side effect (queued on an audit-dispatch outbox). It is clearly distinguishable from siblings like cancel_audit or list_projects 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?

The 'Admin:' prefix sets the privilege context and the phrasing 'full audit run' implies the trigger scenario, but the description never states when this should not be used or points to cancel_audit as the inverse operation. Usage is clear, exclusions are absent.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds that this is an admin action and that it involves a bot-token secret reference, but it does not disclose that existing Slack settings may be overwritten, how the secret reference is handled, or what confirmation is returned.

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, and the administrative framing is placed first. It is efficient, though its brevity contributes to the missing usage and parameter details.

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

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

This is a destructive, idempotent mutation involving sensitive bot-token references, with five parameters at 0% schema coverage and no output schema. A single sentence cannot adequately cover the undocumented 'as_agent' parameter, overwrite behavior, secret handling, or expected outcome, leaving significant gaps for an agent to call it correctly and safely.

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 carry the burden. It indirectly names the workspace, default channel, and bot-token secret fields, but it never mentions the 'as_agent' parameter or clarifies which fields are required versus optional, nor does it explain formats for IDs or secret references.

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

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

The description uses a specific verb ('configure') and resource ('Slack workspace, default channel, and bot-token secret reference for a project'), and names the exact settings it modifies. It is clearly distinguishable from all sibling tools, none of which touch Slack configuration, though it does not explicitly state what it is not.

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

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

The 'Admin:' prefix implies this is an administrative operation, giving some usage context, but there is no explicit guidance on when to use this versus any alternative, no stated prerequisites, and no exclusions. Usage is implied rather than explained.

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

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

Annotations already declare a non-destructive, idempotent, closed-world write. Beyond that, the description discloses the side effect of triggering a board sync that moves the card and the failure mode 'stale_claim' for an invalidated token, which are meaningful additions. It stops short of saying what the tool returns or what happens if the board sync itself fails.

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 with no filler: the action first, then the side effect, then the precondition and error. Every sentence carries distinct information an agent needs before calling.

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

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

For a two-parameter idempotent mutation with no output schema, the description covers the transition, the sync side effect, and the token failure mode. The remaining gap is the undocumented as_agent parameter and the absence of any statement about the response shape.

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 carries the burden of two parameters. It adds real meaning for ClaimToken (original claim token, stale token returns stale_claim) but says nothing at all about as_agent, leaving half the signature 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?

The description names a specific state transition ('claimed' to 'in_progress') on a specific resource (a claimed task), which is far more precise than the sibling mark_task_status. It never names an alternative tool or explicitly contrasts itself with mark_task_status, so it falls short of full sibling differentiation.

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 the precondition clearly (the task must already be claimed and you must hold the original claim token), which tells the agent when this tool is applicable. It gives no explicit exclusion or pointer to alternatives such as mark_task_status or release_claim when the precondition is not met.

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

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

Annotations already establish that this is a non-read-only, non-idempotent, closed-world mutation, so the description correctly focuses on consequences: it names the exact state transition (task moves to review), the audit-finding append behavior, and a specific failure mode (retry_cap_exceeded at the plan's retry cap). That retry-cap disclosure is real value beyond the annotations. Minor gap: it does not say what happens to an existing claim or whether the submission itself can be retried after a cap error.

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 verb and payload, then branching behavior, then the failure condition — a sensible order with no filler. The payload enumeration is long but each item is distinct information rather than padding.

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

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

For a write tool with no output schema, the description covers the important things an agent needs: what to send, what state change results, and one named error condition. The remaining gap is the claim lifecycle relationship (how ClaimToken is acquired and whether it is consumed), which matters given the retry-cap semantics but is absent.

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 carry parameter meaning, and it partially does by enumerating the logical contents of the nested Attempt object (files changed, approach, side effects, build command, test scenario, diff reference). However, it never names the actual keys or the structure of that nested object, and it says nothing about ClaimToken (the sole required parameter) or as_agent, leaving the agent to guess how the claim token is obtained and what as_agent changes about identity.

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 immediately enumerates the payload it carries (files changed, approach summary, side effects, build command, test scenario, diff reference). It also distinguishes the two distinct effects by task type: dev-plan tasks transition to review, audit findings record into the finding's attempt chain, so an agent can tell it apart from submit_findings or submit_attempt_verdict.

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

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

The description gives clear triggering context: you call it when handing off completed work on a dev-plan task or when recording a fix attempt against an audit finding, and it names the resulting state transition. It does not, however, contrast with the adjacent siblings submit_attempt_verdict or submit_review_decision, so the agent must infer that this is the pre-review submission rather than the verdict step.

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?

Discloses real side effects the annotations cannot: state transitions, that fix_failed is gated by a retry cap, and that partial auto-creates a child finding. Consistent with readOnlyHint=false and destructiveHint=false. Missing only whether the transition is reversible or what happens when the retry cap is exceeded.

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

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

Dense, telegram-style sentences, but each one carries a distinct rule and the verdict set is stated up front. 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?

There is no output schema, and the description never says what the tool returns after a verdict is submitted. Combined with the undocumented Evidence and as_agent parameters, an agent has to guess at part of the call 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%, so the description carries the burden. It documents the Verdict values and the conditional CommitHash requirement, but leaves Evidence and as_agent entirely unexplained, which matters for a nested-object parameter.

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

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

Names a specific verb (submit) and resource (a fix-verifier's verdict on a fixer's attempt), and the 'Audit-plan:' prefix scopes it to the audit workflow. An agent can distinguish it from submit_verification_verdict and submit_review_decision because it clearly sits at the attempt-verification stage.

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

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

Explicitly states the outcome each verdict produces (fix_confirmed → fixed, fix_failed → still claimable, partial → child finding), which tells the agent which verdict to pick for a given situation. It does not, however, contrast itself with the sibling override_verdict or state when not to use it.

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

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

The description provides critical behavioral logic not in the schema or annotations: the conditional state machine. It specifies that an empty list results in a direct 'done' transition, while a non-empty list forces a transition to 'review' and auto-creation of findings.

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 tool uses exactly two sentences to convey highly complex workflow logic and branching outcomes, demonstrating perfect conciseness.

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?

Since there is no output schema, the focus is on input functionality. The description covers all necessary operational contexts, including the conditional outcomes based on the input data.

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%, requiring the description to carry the burden. However, the description only mentions 'findings' generally and adds no context or semantics to the required 'ClaimToken' or 'as_agent' parameters, leaving them undocumented functionally.

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 exactly what the tool submits (findings) and explicitly limits its operational context to 'Audit-plan only.' It distinguishes the result based on the content of the Findings array.

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 defines its scope by stating 'Audit-plan only,' effectively narrowing its place in the workflow. While it doesn't name alternatives, the context is sufficient to prevent misuse.

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

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

Annotations only declare the generic profile (not read-only, not destructive, not idempotent); the description goes well beyond that by spelling out the state machine: approved moves the task to done and records commit_hash on the latest attempt, changes_requested below the retry cap returns it to pending for anyone to claim, and at cap it goes to needs_human_review. What is missing is reviewer authorization requirements and whether a submitted decision can be revised afterwards.

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 purpose, then the two branch outcomes in a compact enum-style summary; every sentence carries real state-transition information. The 'decision ∈ {approved, changes_requested}' notation is terse but appropriate, and 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 non-idempotent mutation with no output schema, the description covers the essential consequences of each call, which is what an agent most needs before invoking it. It falls short only on the undocumented Comments/as_agent parameters and the absence of any note on permissions or result reporting.

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 none of the five fields carry enums, so the description must compensate: it supplies the Decision enum (approved, changes_requested) and explains that CommitHash is optional and gets recorded on the latest attempt. TaskId is self-evident, but Comments and as_agent are never explained, leaving two of five 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 and resource: a reviewer's verdict on a task that is in review, with the two allowed decision values. An agent can tell this is a review-submission action, though the description never names the closely related siblings (submit_verification_verdict, submit_attempt_verdict, override_verdict) to disambiguate which verdict tool applies where.

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

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

Usage is implied by 'a reviewer's verdict on a task in review' plus the decision enum, so the context of use is inferable. But there is no explicit when-not-to-use guidance and no routing to alternatives such as override_verdict or the other submit_*_verdict tools, leaving the agent to guess which submission tool fits a given review situation.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent mutation. The description adds real value by disclosing the write target (verdicts table) and the side effect (finding status transitions), but it never says whether resubmitting revises an earlier verdict, which matters given idempotentHint=false.

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 with the scope constraint front-loaded and no filler. The 'etc.' in the evidence sentence and the fragment style make it slightly terse for a mutation tool, but nothing is wasteful.

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 4-param mutation with no output schema and zero schema coverage, the description covers purpose, allowed verdict values, evidence capture, and the resulting state transition. The required ClaimToken and the non-idempotent re-submission semantics remain unaddressed.

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 carry the parameter load. It does supply the Verdict enum values (confirmed, rejected, ambiguous) and identifies Evidence as pre_output/post_output-style data, but leaves the required ClaimToken and as_agent completely 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 (submit) and resource (verifier's verdict on a pending-verification finding), and the 'audit-plan only' qualifier scopes it. It implicitly separates itself from submit_attempt_verdict and submit_review_decision by naming the verifier role and the verification stage, though it does not name those siblings 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' plus 'pending-verification finding' implies the workflow position (after claim_next_finding_for_verification), but no explicit when-not or alternative is given. An agent must infer that this is not the tool for attempt verdicts or review decisions.

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