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

With no annotations, the description carries the full burden and does well: it discloses blocking rules (unresolved or partially fixed findings and not_met or unverifiable delivery results block passing), the ownership precondition (reviewRunId must own the current review), and the risk-tiered outcome (low-risk auto-completes, medium/high wait for developer approval). It stops short of saying what the caller receives on success versus rejection.

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 dense sentences, front-loaded with the action and its payload, then constraints, then outcome semantics. No filler, though the middle sentence is heavy and packs schema detail that could be split for readability.

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 7-parameter, no-annotation, no-output-schema mutation tool, the description covers the decision-relevant behavior well but leaves the closure-to-finding mapping and the success/failure response shape undocumented. An agent can call it, but may mis-structure findingClosures on the first attempt.

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 explain the repeated finding fields (issue, suggestion, severity, trigger, impact, evidence, optional location) and the reviewRunId ownership constraint. Gaps remain: findingIndex is never explained even though it is the only mechanism linking a closure to a prior finding, and taskId and actorLabel are unaddressed. The mention of "not_met" also does not match any value in the closure status enum.

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 ("Pass the claimed review") and enumerates the payload it carries, which cleanly separates it from siblings like request_changes or complete_review. It does not name those siblings explicitly, so the distinction is inferred rather than stated.

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 conditional path clearly: "When the previous round requested changes, record a closure status for every previous finding." However, it never contrasts this tool with request_changes or complete_review, nor does it say when to call it versus continuing review, so the agent must infer the branch point.

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

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

With no annotations, the description carries the full behavioral burden, and it does well to disclose read-only local scope and the explicit non-actions (never merges, fetches, pushes, or substitutes another commit SHA). It does not say what happens on check failure, whether retries are rate limited, or what a retry actually re-evaluates.

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: purpose and scope first, then parameter provenance, then the safety boundary. No filler and the most important constraint is front-loaded.

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

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

For a three-parameter tool with zero annotation coverage and no output schema, the definition covers the safety profile but leaves the actorLabel parameter and the outcome of a failed retry unexplained, so an agent still has gaps before calling it correctly.

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

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

Schema description coverage is 0%, so the description must explain all three parameters. It only covers expectedReviewId, and even then only its source ('from get_task'); taskId is unmentioned and actorLabel is never addressed 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 and resource: 'Retry the local read-only Git integration check', scoped to 'an already accepted latest review'. An agent can distinguish it from siblings like approve_review or get_task, though the boundary with other review-related tools is only implied.

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

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

The precondition ('for an already accepted latest review') and the instruction to take the id from get_task give useful context, but there is no explicit when-not guidance and no named alternative tool for the case where a check should be started rather than retried.

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

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

With no annotations provided, the description carries the full burden, and it does substantial work: it discloses validation rules, rejection conditions, a required local-branch state, and an asynchronous approval gate keyed to task risk level. What it omits is the response shape, idempotency/retry behavior, and any authorization requirement, which matters for a write operation of this complexity.

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, purpose front-loaded, then constraints in descending order of importance, with the branch-state and approval-gating rules consolidated at the end. The semicolon-joined clauses make the last sentence dense, but no sentence 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?

For a tool with 7 required parameters, nested arrays of evidence objects, and no annotations or output schema, the business rules are well covered but the callable surface is not. An agent still cannot tell what a successful response contains or how to construct findingClosures entries from the description 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 8 parameters, so the description must compensate. It signals that findings, findingClosures, and verificationEvidence are the structured payload and implicitly ties closure status values (not_fixed, partially_fixed) to pass rejection, which adds real meaning. It says nothing about taskId, reviewRunId, summary, actorLabel, or how findingIndex maps onto the findings array, so the weighted 3 reflects partial compensation.

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: 'Record a passed or changes-requested AI review with structured findings, finding closures, and verification evidence.' That is far more informative than the bare name. It stops short of distinguishing itself from siblings like approve_review or request_changes, which occupy adjacent decision-recording territory.

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 conditions under which a 'passed' decision is rejected (unmet or unverifiable acceptance criteria, prior not_fixed/partially_fixed findings) and the risk-based gating (low-risk auto-completes after the branch check, medium/high wait for developer approval). That is genuine usage context. However, it never says when to call this versus approve_review, request_changes, or start_review, leaving sibling routing to inference.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose a meaningful workflow trait: agent-created tasks are provisional in the inbox and are not ready until a developer confirms and orders them. It omits other behavior an agent would want — what is returned (e.g. the new task id), whether duplicate or invalid dependency ids cause failure, and whether anything is auto-approved by riskLevel.

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 and inbox/provisional status are front-loaded, and the subsequent sentences all carry actionable rules rather than filler. The two parallel 'Before creating a task…' / 'When creating a task…' openers are somewhat redundant and could be merged, but nothing is off-topic.

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 7-parameter creation tool with no annotations and no output schema, the description covers the things the schema cannot: inbox staging, the confirmation gate, and acceptance-criteria quality rules. Only the return value and failure modes are unaddressed, which is a modest gap rather than a blocking one.

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

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

Schema coverage is 71%, so baseline is 3; the description adds valuable meaning for acceptanceCriteria and objective (independently verifiable result plus matching verification, no smuggled implementation constraints). However, its only nod to a named parameter is "the model label," which does not obviously map to actorLabel, and dependencyIds, sourceTaskId, and riskLevel are left entirely to the schema.

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

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

The description gives a specific verb and resource — "Record one newly discovered task in the project's inbox" — including the singular scope and destination. It does not distinguish itself from the sibling create_tasks (batch) or edit_inbox_task, so the agent must infer the boundary from the name alone.

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 preconditions and a clear when-not: only proceed if the agent can state the observable outcome, exclusions, and verification; otherwise ask the developer instead of guessing. It does not mention alternatives such as create_tasks for multiple tasks or sourceTaskId-scoped follow-ups, so the routing guidance is incomplete but the usage gate itself is strong.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the most important trait: the whole batch is rolled back if any single input is invalid. It says nothing, however, about permissions/authorization, ordering, size limits, or what a successful call returns (no output schema exists to cover that).

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 atomic-batch behavior and rollback guarantee are front-loaded, which is the right ordering. The latter two sentences are lengthy and partly restate the acceptanceCriteria schema description, so a little editing would tighten it without losing meaning.

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

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

For an unannotated mutation tool with no output schema, this covers the failure mode (atomic rollback) and authoring discipline but omits the success contract, any permission prerequisites, and cross-project dependency validation. An agent could call it, but would be guessing about the result and preconditions.

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?

Top-level schema coverage is 0% for the single `tasks` parameter, but the description compensates by explaining the batch container's semantics and by adding quality constraints on acceptanceCriteria and dependency handling that go past the nested field descriptions. It still does not describe the per-task object shape or which fields are required beyond what the schema states.

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

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

The description gives a specific verb and resource ("Record several newly discovered inbox tasks") and adds the defining traits: batch, atomic, optional model labels. "Several ... atomically" implicitly separates it from the singular sibling create_task, though it never names that sibling explicitly.

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

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

Provides real when-to-use guidance: only create a task once you can state the observable outcome, explicit exclusions, and verification, and ask the developer rather than guessing when requirements are unclear. It also gives criteria-quality rules. What's missing is explicit routing to create_task for single tasks, which forces the agent to infer the batch-vs-single boundary.

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

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

With no annotations, the description carries the full burden and does most of it: it discloses optimistic-concurrency rejection via expectedUpdatedAt, a field-level restriction (risk level and risk confirmation cannot change), a state precondition (inbox only), and replacement semantics ('pass the complete title, objective, acceptance criteria, and dependencyIds'). Remaining gaps are the response/return behavior and what happens to the task after a successful edit, plus the unmentioned actorLabel.

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 in a deliberate order: purpose, required call protocol, constraints, and the alternative tool. Nothing repeats the schema verbatim and no sentence could be dropped without losing a distinct piece of guidance.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the hard parts — concurrency safety, state gating, immutable fields, and sibling routing. It stops short of describing the success outcome and permissions for editing another agent's task, which matters given the 'you or another agent' scope.

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 only 14%, so the description must compensate, and it mostly does — it ties expectedUpdatedAt to get_task's updatedAt and clarifies that title, objective, acceptanceCriteria, and dependencyIds must be supplied as complete values rather than partial patches. It leaves actorLabel and the taskId-to-get_task relationship undefined in prose.

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

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

States a specific verb and resource — 'Correct the definition of an inbox task' — and bounds the scope by explicitly naming the alternative for run-scoped progress, update_task. An agent can distinguish this from update_task, create_task, and get_task without opening any schema.

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

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

Gives an explicit precondition (call get_task first and pass the latest updatedAt), a state gate (only works while the task is in inbox), and a named alternative (update_task for run-scoped progress). When-to-use and when-not-to-use are both stated, not 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?

With no annotations supplied, the description carries the load and does state 'Read-only' plus a version-determinism guarantee (identical to what init generates for this version). It does not say what an existing file implies for the result or the exact return format, but for a zero-parameter read tool the disclosure is largely sufficient.

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, safety qualifier first, then what it returns, then when to call it. Every sentence adds information and nothing is redundant.

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

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

For a no-param, no-output-schema read tool, the definition covers what is returned and when to use it. The only minor gap is the concrete return shape (e.g., markdown text vs. structured field) and any size caveat.

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

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

The tool takes no parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate at the input level.

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 ('Returns the full MileStack agent instructions') and pins down exactly what the payload is by equating it to the .milestack/agent-instructions.md file generated by milestack init for this version. No sibling tool does anything similar, and the definition makes that distinct role obvious.

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 condition: 'Call it when that file is missing in the current checkout.' This also implies the exclusion (when the file is present, read the file instead), so the agent knows the alternative without 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?

No annotations are supplied, so the description carries the full burden. It does disclose meaningful behavior: the output is an ordered ready queue, waiting tasks include unfinished dependencies, and results contain task summaries only, without objective or acceptance criteria. It does not state that the operation is read-only, or say how the view parameter changes the payload; 'read' implies read-only but leaves it implicit.

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 triggering condition, then the selection rule, then the limit on what the results contain and the pointer to get_task. Every clause earns its place with no restatement of the tool name.

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

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

For a one-optional-parameter read tool with no output schema and no annotations, the description covers purpose, routing, and the shape of results well. The one clear gap is the meaning of the compact and full views, which is the only thing that changes what the caller gets back.

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

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

The schema coverage is 0% and the single parameter 'view' (compact vs full) is never mentioned in the description. The description does say results omit objective and acceptance criteria, but since the view enum likely controls exactly that, it leaves the two levels of detail undefined and possibly ambiguous.

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: read the current project work and the ordered ready queue. It also sets the scope apart from the sibling get_task by saying results are summaries, not full definitions, so an agent can distinguish the two tools without opening either schema.

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

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

It gives an explicit selection condition ('Use this when no taskId is known'), an explicit alternative (call get_task for the full definition), and downstream guidance on which returned tasks to act on ('Choose only ready tasks with runnable=true'). It also explains that waiting tasks carry their unfinished dependencies, which prevents misinterpreting queue entries.

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

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

With no annotations, the description carries the full burden and does well: 'Read' establishes it as non-mutating, and it enumerates exactly what the working view returns, including current run progress and per-criterion delivery results. It also flags the 'full' view as immutable history. It stops short of noting payload size or cost of view='full', which matters for a history dump with no output schema.

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

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

Front-loaded with the core action, then the return contents, then the view switch and the sibling-ordering note. The middle sentence is a long enumerated list, but each element is substantive rather than filler. Slightly dense, though nothing is truly 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?

No output schema and no annotations mean the description must describe returns, and it does so thoroughly for both views. Remaining gap is failure behavior for an unknown taskId and any guidance on the size/latency of view='full'.

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 define parameters, and it does: it spells out the default 'working' view's contents versus view='full' returning complete event and review histories. taskId is only characterized as 'known', leaving error behavior for an invalid or stale id unstated.

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 (read) and resource (a known taskId's definition plus phase context), and the 'known taskId' phrasing immediately separates it from list_tasks and get_project_status. An agent can tell this is the per-task detail fetch without opening the schema.

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

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

The 'known taskId' framing plus 'This does not require get_project_status first' gives clear entry conditions and removes a dependency-ordering ambiguity relative to a sibling. It also explains when to switch to view='full'. It does not explicitly say when not to use it (e.g., in favor of list_tasks when the id is unknown), so it falls short of a 5.

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

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

With no annotations supplied, the description does real work: it declares the operation read-only, discloses result ordering (ready-queue or recent-completion), states that results are bounded, and warns that the cursor is opaque. It does not cover cursor expiry, invalid-cursor behavior, or whether results are scoped to a project or workspace.

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 scope and ending with the alternative-tool pointer. Each sentence carries information, though 'existing ready-queue or recent-completion ordering' is slightly vague for a sentence that is meant to be precise.

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

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

No output schema exists, so the description compensates by describing the shape of each item as a summary lacking objective and acceptance criteria. For a simple three-parameter read-only list, that is nearly complete; only ordering-per-status and the end-of-pagination signal are left implicit.

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 burden. It conceptually covers all three parameters, calling the cursor opaque (do not parse it) and the limit bounded, but it never explains the status enum values or how status selects the ordering.

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: read one task status section, with bounded limit and opaque cursor. It explicitly distinguishes itself from get_task, which returns the full definition, so an agent can choose between them without opening either schema.

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

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

The final clause gives a clear routing rule: use this for summaries, call get_task for the full definition. It stops short of stating exclusions, such as which ordering applies to which status or whether other siblings cover cross-status queries.

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

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

With no annotations, the description carries the behavioral burden well: it discloses the rework intent, the requirement to close all prior findings, reviewRunId ownership, and the state transition back to ready requiring a new execution runId. It does not cover permissions, error behavior, or full side effects, but the core state-changing behavior is clear.

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

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

The description is three dense sentences with no wasted wording. The action is front-loaded, followed by the key validation rule and then the ownership/state-transition behavior.

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

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

For a mutation tool with six parameters, nested finding arrays, no annotations, and no output schema, the description covers the critical business rules and state transition. It still leaves some parameter semantics and failure modes unexplained, but it is largely complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It adds important meaning for findings (trigger, impact, evidence), findingClosures, and reviewRunId ownership, but it does not explain taskId, summary, actorLabel, findingIndex, status values, or the command/result evidence structure.

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 a specific review action: returning a claimed review for rework with actionable findings and finding closures. This distinguishes it from approval or completion actions, though it does not explicitly name the sibling alternatives.

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

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

It gives clear context for when to use the tool: returning a claimed review for rework and requiring every previous finding to be closed on re-review. It also states a key ownership prerequisite for reviewRunId, but it does not explicitly contrast this with approve_review or give when-not guidance.

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

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

With no annotations, the description carries the full burden and does so: the claim is atomic, the reviewRunId must be persisted, the exact commit of the latest submission is reviewed, and pass/fail gating rules (any not_met/unverifiable criterion or not_fixed/partially_fixed finding blocks a pass; severity does not override) are spelled out.

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 text is long but front-loaded with the action sequence (confirm phase, claim, save ID, review) and every clause is operational rather than filler. Density is high, though a single paragraph carrying both invocation steps and review policy makes the workflow rules slightly harder to scan.

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

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

For a workflow-gating tool with no output schema, the description covers invocation order, review substance, and conclusion steps well. It stops short of stating what else the claim returns besides reviewRunId or what to do if no pending review exists, which an agent would need in a race or empty-queue case.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It conveys that taskId comes from the developer's review request, but actorLabel is never mentioned and taskId's format or provenance is only implied, leaving one of two parameters undocumented.

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

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

The description states a specific verb and resource: atomically claim the latest pending review for a task and return a reviewRunId. It is clearly separable from siblings such as submit_for_review, approve_review, request_changes, and complete_review, which are named as downstream steps.

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

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

Explicit preconditions are given (call get_task first and confirm phase=review) and the terminating alternatives are named (approve_review, request_changes, complete_review). It also says what not to treat as evidence (the submitter's criteriaResults), which is a concrete exclusion.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavior: the claim is atomic, a runId is returned, and that runId must accompany every later execution update. However, it omits the failure mode when the task is not ready or is already claimed by another agent, and says nothing about permissions or whether the claim expires — significant gaps for a mutation tool with zero annotation coverage.

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 precondition and the action, each carrying distinct information: sequencing, atomicity, and the runId contract. Nothing is redundant.

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 names the returned runId and its downstream obligation, and it situates the call in the get_task → start_task → update workflow. It falls short only on error/race behavior and on more precise parameter naming.

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

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

Schema coverage is 0%, so the description must compensate for both parameters. It explains the optional label ('model label'), though the naming drifts from the schema's 'actorLabel', and taskId is only implied by 'claim a runnable ready task' rather than described directly. Partial compensation, but not enough to fully cover a 0% documented 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 ('claim a runnable ready task') plus a distinct behavioral trait ('atomically'), which clearly separates it from read siblings like get_task and list_tasks. It does not explicitly contrast with write siblings such as update_task or start_review, so it stops just 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?

'After get_task' gives explicit sequencing, and 'runnable ready task' states the precondition that qualifies a task for this call. There is no statement of what to do when the task is not ready or already claimed, and no named alternative for that case, so it is clear context without exclusions.

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

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

With no annotations, the description carries the burden and does so well: it discloses the state transition to in_review, that the runId becomes invalid after submission, the exact 40-character SHA requirement, and that 'met' requires recorded evidence. It does not cover error behavior, retry/idempotency, or authorization requirements, which keeps it below a 5.

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

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

Two sentences, front-loaded with the action and required payload, then the state-change consequences. Dense but every clause carries unique information with no filler.

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

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

For a nine-parameter mutation with no annotations and no output schema, the description nails the core submission contract and lifecycle effects but omits several optional parameters and says nothing about failure modes or what the caller receives back. Adequate, not complete.

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

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

Schema description coverage is 0% across nine parameters, so the description must compensate. It meaningfully explains commitSha, summary, criteriaResults, criterionId (sourced from get_task), status values, evidence semantics, and runId invalidation, but leaves branch, worktree, actorLabel, and completedWork entirely undefined.

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

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

States a specific verb and resource ('Submit a running task for review') plus the essential payload contract, which cleanly separates it from sibling tools such as start_review, approve_review, and request_changes. An agent can distinguish the action without opening another schema.

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

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

Gives a clear precondition ('running task') and an explicit dependency on get_task for criterion ids, which tells the agent when the call is valid. It stops short of naming alternatives (e.g., use request_changes or start_review instead) or stating failure conditions, so it is strong but not exhaustive.

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

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

No annotations are supplied, so the description carries the full behavioral burden for what is clearly a mutation. It never says whether progress is appended or overwrites prior state, what happens when optional fields like blocker or nextStep are null, or whether a permission/ownership check applies beyond the runId constraint.

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 core action and immediately followed by the constraint and the alternative. No filler, no restatement of the title, and the most decision-relevant routing information comes first.

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

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

For a ten-parameter mutation with no annotations, no output schema, and zero schema-level parameter descriptions, the definition is thinner than the tool's complexity warrants. It does cover the critical correctness constraint on runId, which prevents a common misuse, but the bulk of the payload semantics are undocumented.

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

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

Schema description coverage is 0% across ten parameters, so the description must compensate and it largely does not. Only runId receives any added meaning (it must belong to the current execution); taskId, summary, completedWork, currentStep, nextStep, blocker, requiredAction, handoffNote, and actorLabel are left completely undefined.

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

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

The description states a specific verb and object ("Record run-scoped progress for a running task") and names the sibling it is not (edit_inbox_task for correcting inbox task definitions). That said, "progress" is left abstract relative to the ten schema fields, so an agent cannot fully infer what recording progress entails.

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 supplies a hard precondition ("the runId must belong to the current execution") and an explicit alternative with the condition that selects it ("Use edit_inbox_task to correct an inbox task definition instead"). It gives no guidance, however, on how this relates to lifecycle siblings like start_task, submit_for_review, or complete_review.

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