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

Annotations only say non-read-only, non-destructive, closed-world; the description adds substantive behavior well beyond that: the patch is committed as a new Context version first, read-write project authorization is required, and the backend dispatches the next role and blocks up to wait_seconds. It also gives turn-continuation rules for action_required and a mandatory verbatim prefix from meeting_mode_notice, which are critical behaviors no annotation conveys.

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?

Content is front-loaded with purpose, then alternative, then post-call handling in a logical order, and each sentence carries operational weight. However, the awkward line wrapping splits sentences mid-clause and the multi-clause 'If the result has...' block could be tightened into a compact bulleted set of rules.

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 an output schema present and annotations covering the safety profile, the description need not explain return values; instead it covers what an agent actually needs — auth requirement, version-conflict implication, alternative tool for interrupted rounds, and mandatory follow-up actions on the response. Nothing essential for a correct call 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 100%, so the schema already documents project_id, patch fields, plan_content role-gating, and wait_seconds semantics. The description adds only indirect context (the patch becomes a new Context version), so the baseline 3 applies rather than a higher score for value added.

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

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

States a specific verb and resource ('PM refines one completed Agent result; backend starts the next role') with a clear scope of one execution, and explicitly names the sibling it is not (resume_pending_dispatch) for interrupted rounds. An agent can distinguish it from commit_context_patch or propose_context_patch without opening schemas.

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

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

Gives explicit conditions for use ('Continue this turn whenever workflow says so') and an explicit exclusion with the alternative to use instead ('If an earlier round was interrupted, use resume_pending_dispatch instead'). The trigger phrase 'whenever workflow says so' is somewhat circular, but the exclusion plus the post-call handling rules make the routing clear.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety profile is covered; the description reinforces it with "Read-only" and adds genuinely useful context beyond the annotations: the tool works without any chat history and returns a consolidated bootstrap payload including a context validation result and pending ChatGPT handoffs. It does not discuss size, cost, or failure behavior (e.g., what happens for an unknown or unregistered project_id), 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?

The purpose and read-only/first-call guidance are front-loaded, and the alternative-tool routing is a clean final sentence. The long inventory of recovered artifacts is informative but dense and partly duplicates what the output schema already declares, so it is slightly heavier than necessary.

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-parameter bootstrap tool with annotations and an output schema, the description covers purpose, ordering, safety, and sibling routing, which is everything needed to call it correctly. The enumerated return list is largely redundant with the existing output schema, and error behavior is unaddressed, so it is strong but not exhaustive.

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 a single parameter with 100% schema description coverage, and the schema already tells the agent to use an id from list_projects. The description adds no format, validation, or failure semantics for project_id, so the schema does all the work — the baseline 3 applies.

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

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

"Recover a project's whole working state without any chat history" states a specific verb and resource, and the enumeration of what is recovered (tasks, pending messages, decisions, blockers, handoff, next action) makes the scope concrete. It explicitly distinguishes itself from get_context (one role's view) and get_context_history (past versions).

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?

"Call it first in a new conversation" is an explicit trigger condition, and the closing sentence routes the agent to the correct alternatives with the condition that selects each (per-role view, historical versions). No inference is required to pick between them.

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 and destructiveHint=false, and the description's "Read-only" line restates that rather than adding to it. Where it does add real value is the compression behavior: bounded lists are cut oldest-first, budget_omitted records what was removed, and invariants/source_document_refs/approved_plan/task/reports are never truncated. That is exactly the kind of beyond-schema behavior an agent needs before choosing a budget.

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, then behavior, then the sibling comparison, with no filler sentences. The protected-versus-compressed field list is dense but every item is load-bearing; the parenthetical list of package contents is the only mildly cluttered spot.

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?

An output schema exists, so return values need not be spelled out, and the description still covers the one output concept that affects invocation (budget_exceeded). For a four-parameter read tool with full annotation and schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so all four parameters are already documented. The description still adds meaning by explaining the budget mechanics (roughly 3 characters per token, which parts get shortened, budget_exceeded when protected parts alone exceed the ceiling), which goes beyond the schema's phrasing.

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?

Uses a specific verb ("build") and resource ("handoff package") and enumerates the contents: shared Context, invariants, next action, task and reports. It explicitly contrasts itself with the sibling get_context, so an agent can distinguish the two without opening either schema.

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

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

States the selecting condition plainly: get_context returns the same package without a budget, "so use this tool only when you need to cap its size." That is an explicit when-to-use plus a named alternative, 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 meaningfully beyond the annotations: it warns that results are untrusted data rather than instructions (a real prompt-injection caveat), and that each call cold-starts the server so latency of several seconds is expected. It also discloses the operator-enablement gate. What it omits is that the invoked tool may itself be mutating despite destructiveHint=false on this wrapper, which an agent could misread.

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, each earning its place: capability, permission boundary, then trust and latency caveats. Front-loaded with the core action and 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?

An output schema exists so return values need no explanation, and the description covers the remaining agent-relevant concerns — discovery path, permission gating, latency, and data trust. Nothing needed to invoke this dispatcher correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including that 'arguments' must match the target tool's input schema. The description repeats little of that and adds no syntax or shape guidance beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ('Call one tool of a local MCP server the operator installed for this project') and names the sibling it pairs with (list_installed_mcp_tools). An agent can immediately distinguish this dispatcher from discovery or project-level tools in the sibling 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?

Gives a concrete precondition — only server+tool pairs enabled via the local CLI are accepted — and routes discovery to list_installed_mcp_tools. It lacks an explicit 'do not use when' clause or a mention of when a direct/sibling tool would be preferable, which keeps 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?

Goes well beyond the annotations by disclosing irreversibility ('not undone by resuming'), data retention ('Task history and reports are kept'), and idempotency ('safe to call again'), plus the terminal-state precondition. The only mild tension is with destructiveHint=false, but the description resolves it by clarifying that no history or reports are destroyed, so this reads as a state change rather than data destruction.

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 short sentences, front-loaded with the action and its effect, then the irreversibility warning, then retention/idempotency, then the precondition and alternatives. No filler and no restatement of the name 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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. For a two-parameter mutation tool, everything an agent needs to decide and call correctly — preconditions, reversibility, idempotency, and alternatives — is present.

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

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

Schema description coverage is 100% and both parameters (task_id, project_id) are documented in the schema with pointers to the tools that produce them. The description adds no further meaning about the parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('Stop a task') and then spells out the two concrete effects: marking the task cancelled and asking the running worker to terminate its agent process tree. That level of specificity distinguishes it cleanly from siblings like resume_pending_dispatch, recover_workers, and reevaluate_execution.

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

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

Gives an explicit when-to-use condition ('use it only when the user wants the work abandoned') and names two alternatives with the situation that selects them ('To get a stuck execution moving instead, use recover_workers or resume_pending_dispatch'). It also states a when-not condition: a task that already COMPLETED or was REJECTED cannot be stopped.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is structured data. The description nonetheless adds real context beyond that: it asserts explicitly that the call "changes and proposes nothing" and outlines the downstream commit path, which tells the agent this is a safe pre-read in a multi-step flow. It stops short of describing return volume or pagination, so not 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?

Three sentences, front-loaded with the verb and the payload enumeration, then the workflow, then the disambiguation. Every clause carries information; nothing is restated from the name or title.

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?

An output schema exists and annotations cover safety, so the description's remaining burden is workflow placement and differentiation from siblings — both delivered. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100% and the single project_id parameter is already documented as coming from list_projects. The description adds no additional parameter meaning (no format, scoping or validation notes), so the baseline 3 applies with the schema doing the work.

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 ("Gather") and enumerates the exact resource set returned: context_version, tasks, events, agent reports, decisions, evidence artifacts, sync status and context file locations. It explicitly separates itself from validate_context and positions itself in the patch workflow, so an agent can distinguish it from siblings like get_context or propose_context_patch.

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 ("before writing a ContextPatch"), a follow-on sequence (propose_context_patch then commit_context_patch), and a named alternative with its selecting condition ("To only check integrity use validate_context"). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations only declare readOnly=false, destructive=false, openWorld=false. The description goes well beyond them, disclosing base-version revalidation, rejection semantics for stale bases, atomicity of the commit, evidence retention, and immutability of committed versions — precisely the failure modes an agent needs before mutating state.

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

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

Front-loads the action, then layers precondition, failure mode, and follow-up path in a tight sequence with no redundant sentences. Every clause carries operational 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?

Given a simple two-parameter mutation with full schema coverage, annotations, and an output schema, the description supplies the remaining essentials: ordering with respect to propose_context_patch, atomicity, staleness rejection, and immutability. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with both patch_id and project_id documented including the producing tool for each ID. The description adds no further parameter-level meaning (for instance, it never explains how base_context_version relates to the call, since that field is not a parameter here), so the baseline 3 applies.

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

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

States a specific verb and resource ('Apply a proposed ContextPatch as a new Context version') and implicitly separates itself from the sibling that produces patches, propose_context_patch, and from the reader, get_context_history. An agent can identify the operation 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 precondition ('Call it only after reading the diff from propose_context_patch') and an explicit route to the alternative for inspecting results ('read them with get_context_history'). The rejection condition for stale base versions is also named, so the agent knows when the call will fail.

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 by disclosing refusal conditions (existing id or folder) and a containment guarantee ('never touches a folder outside that directory'), which the readOnly/destructive/openWorld hints do not convey. It stops short of stating required permissions, side effects on failure, or whether a partially created folder is rolled back.

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

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

Front-loads the core action and constraints, then routes to alternatives in a single closing sentence with no filler. Slightly verbose in the middle clause ('To work on an existing folder the operator registers it locally instead'), 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?

For a two-parameter creation tool with an output schema and clear annotations, the description covers action, location, initialization, refusal cases, and sibling routing. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so project_id and language are already documented in the schema, including the enum-like language values. The description adds only the uniqueness/reuse constraint on project_id ('refuses an existing id'), matching the baseline for schema-documented 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 ('Create and register a brand-new project') plus where it lands ('a new folder under the operator's configured projects directory') and that it is Git-initialised. This distinguishes it cleanly from siblings like start_project_request and bootstrap_project without opening either schema.

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

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

Gives explicit when-not conditions and names the alternatives: existing folder → register it locally; already-registered project → start_project_request; inspection → bootstrap_project. An agent has a complete routing decision from this text alone.

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 is a non-read-only, non-destructive, closed-world operation; the description adds that the call dispatches the first step and blocks/wait for settlement, and documents the post-call contract around action_required and meeting_mode_notice. It does not spell out failure modes or what state is created on error, so it falls short of full transparency but clearly exceeds the annotation baseline.

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

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

The most decision-relevant fact (alias of start_project_request, prefer the original) is front-loaded, and the remainder is conditional post-call handling. It is dense rather than padded, though the turn-management instructions ("do NOT end your turn", verbatim first line) are verbose relative to the tool's own 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?

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. What remains for the description to supply, namely sibling routing, blocking behavior, and required follow-up on action_required/meeting_mode_notice, is all present.

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

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

Schema description coverage is 100%, so every parameter already carries its own documentation, including the note that task_id is ignored. The description repeats the task_id-ignored point and adds nothing about workflow, acceptance, project_id, requirement, or wait_seconds beyond what the schema states, so baseline 3 applies.

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

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

The description names the concrete operation ("start a NEW project request, dispatch the first step, and wait") and explicitly frames the tool as a compatibility alias of start_project_request, so an agent can distinguish it from the sibling that should normally be used.

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 routing guidance ("Prefer start_project_request"), an explicit prohibition ("Never use it to continue an existing task"), and a downstream rule ("Do not call dispatch_agent again; continue according to workflow"). The only minor ambiguity is that it never says why the alias still exists, but the when/when-not picture is complete.

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 readOnly=false, destructive=false and openWorld=false; the description adds that execution is real (no simulated option), that the call blocks and waits for progress, and that a non-null action_required obligates the agent to continue rather than end its turn. The verbatim-first-line rule for meeting_mode_notice is behavior an agent could not derive from structured fields.

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

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

Front-loads the action and scope, then routes to alternatives, then gives the follow-up obligations in priority order. It is longer than most descriptions and slightly repetitive ('for example wait_for_task again'), but each clause carries operational weight rather than filler.

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

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

With an output schema present, the description need not explain return values, and it covers the main loop: dispatch, wait, handle action_required, surface meeting_mode_notice. It omits what failure or version-conflict conditions require of the caller and does not point to resume_pending_dispatch or cancel_task, but nothing essential for a correct first call 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 100%, so role, task_id, project_id, instruction, wait_seconds and context_version are already documented, including the wait semantics and version-conflict rejection. The description only reinforces that the role should come from get_task_status, adding marginal meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Dispatch the configured provider with real execution and wait for progress') and explicitly distinguishes the tool from start_project_request and advance_project by naming them. An agent can tell what this does and what it does not do 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 explicit when-to-use ('run a role of an existing task manually, for example a role named by get_task_status') plus two named alternatives with the conditions that select them ('to start a new change use start_project_request', 'to move on after a finished result use advance_project'). It also prescribes post-call behavior for action_required and meeting_mode_notice, 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?

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the description carries most of the load — and it does well: no new LLM call, config-flag prerequisite, idempotent skipping of already-scored roles, and 'never changes the task's own state — purely a side record'. The only minor gap is that it doesn't say what happens when the engine is disabled (error vs no-op).

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 mechanism, and each subsequent sentence carries a distinct, useful fact (prerequisite, skip behavior, alternative tool, state safety, result retrieval). Slightly dense with parenthetical asides and odd line wrapping, 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?

Output schema exists, so return values need no explanation, and the description still points to get_task_evaluations for reading results. Combined with the prerequisite, idempotency, and state-safety notes, an agent has everything needed to invoke this correctly against a 4-parameter, non-read-only side-effect tool.

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

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

Schema description coverage is 100%, so role, task_id, task_type and project_id are already fully documented in the schema, including the 'omit for current workstream task' default. The description reinforces 'every role' for the role parameter but adds no syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Score the latest successful execution of every role on this task') and immediately constrains the mechanism ('rule-based arithmetic; never a new LLM call'). It is clearly distinguishable from the sibling reevaluate_execution (single forced re-score) and get_task_evaluations (reads the results).

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

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

Gives explicit when-to-use and when-not-to-use guidance: it skips roles already evaluated for their latest execution, and reevaluate_execution is named as the alternative when a fresh version is wanted. It also states the prerequisite that evaluation_engine must be enabled, including the exact config command.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds real context beyond that: data comes only from verified PASSED/FAILED evaluations, and the low_sample flag signals when history is insufficient to trust the number. It does not describe grouping/pagination mechanics, but an output schema exists to carry return structure.

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 short sentences, front-loaded with what is read and at what scope, then caveats, then the alternative tool. Every sentence carries information; nothing restates the tool name or schema redundantly.

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 read-only, zero-required-parameter query tool with full schema coverage, an output schema, and complete annotations, the description covers scope, data provenance, the low_sample caveat, and sibling routing. Nothing needed to select or invoke it correctly is missing.

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

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

Schema coverage is 100%, so each filter is already documented with examples in the schema. The description adds combining semantics ('all three filters are optional and combine') that the schema does not express, which is genuine value over the structured fields.

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 metric ('Read Beta-Bernoulli reliability') over an explicit scope ('across every project on this home') with named grouping dimensions (agent/model/role/task_type). It also names the sibling get_task_evaluations and the boundary between them, so an agent can distinguish the two 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 explicit routing: use this for home-wide reliability, use get_task_evaluations for one task's own scores. It also clarifies that the tool is not tied to one project and that all three filters are optional and combinable, which covers the main usage decision points.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description still adds real value by stating the tool can never grant approval and where approval actually comes from (operator locally / project write authorization). That prevents a common agent misuse. It stops short of mentioning pagination or result-count limits, though the output schema reduces the need to describe return values.

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 purpose and ordering come first, followed by the read-only constraint and the routing to a sibling. Two dense sentences with no filler; the clause about where approval comes from earns its place by closing an exploitable 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?

For a two-parameter read-only lookup with full schema descriptions and an output schema, nothing an agent needs is missing: purpose, ordering, safety boundary, and the sibling alternative are all covered.

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

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

Schema description coverage is 100%, so both project_id and task_id are already documented in the schema with cross-references to list_projects and get_task_status. The description adds no additional meaning about these parameters, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read the plan-approval records of a task') plus the ordering ('newest first'), and explicitly differentiates itself from the sibling get_task_status. An agent can distinguish it from the other 40+ tools 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 a concrete triggering scenario ('before an implementation role writes files') and names the alternative for the adjacent need ('for the task's overall state use get_task_status'). Both when-to-use and when-to-use-something-else are present.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description's 'Read-only' sentence is largely redundant. It does add real behavioral context beyond the annotations: results are pinned to the current context_version and every fact carries provenance, which matters for reproducibility. It stops short of describing pagination or size limits, but for a read-only retrieval tool that is minor.

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 purpose and content list come first, followed by the safety note and then a compact alternative-routing sentence. Every clause carries information, though the 'Read-only' restatement of annotations and the parenthetical tool list make it slightly longer than strictly necessary.

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 four-parameter read tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what comes back, how it is scoped, when to choose a sibling, and what to do with the returned context_version. No material gap remains.

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

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

Schema description coverage is 100%, so the schema already explains role, scope, task_id, and project_id with defaults and accepted values. The description only reinforces that the package is role-specific and version-pinned; it adds no syntax or format detail the schema lacks. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Read') on a specific resource ('the project's shared Context') and enumerates the package contents (purpose, invariants, architecture, progress, next action, provenance, available_skills). An agent can distinguish it from get_context_history, bootstrap_project, and build_handoff 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?

It states the primary use case ('brief yourself before acting as a role'), names three alternatives with the conditions that select them (bootstrap_project for fresh chats, get_context_history for older versions, build_handoff for token budgets), and notes the downstream tools that consume the returned context_version.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the 'Read-only' sentence is largely redundant. The description still adds real behavioral context beyond the annotations: the history is immutable, results are ordered oldest first, and each entry carries commit metadata plus a diff against the prior version. It stops short of describing paging behavior or how much history exists, which keeps it from a 5.

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

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

Two sentences, front-loaded with what is returned, then safety, then usage and the alternative. Every clause carries information: immutability, ordering, per-version diff, and the sibling hand-off. No filler or restatement of the tool name.

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

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

An output schema exists, so the description needn't explain return values, and the input schema fully covers the three parameters. What remains for the description to carry is scope, ordering, immutability and sibling differentiation, all of which are present. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so limit, offset and project_id are already documented in the schema, including offset's 'skip from the oldest' semantics. The description's 'oldest first' phrasing reinforces the ordering assumption behind offset but adds no new parameter detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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 project's immutable Context versions') and qualifies scope with ordering and payload ('oldest first, each with its commit metadata and a diff against the previous version'). It explicitly routes away from the closest sibling by naming get_context for the current Context, so an agent can distinguish the two 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?

It gives two concrete use cases ('audit how the Context changed' and 'find an older context_version') and names the alternative tool with the condition that selects it ('for the current Context use get_context instead'). This is explicit when-to-use plus a named alternative, leaving little 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?

Annotations already cover safety (readOnlyHint=true, destructiveHint=false), so the bar is lower; the description still adds real value by disclosing that the record is empty unless Meeting Mode ran for the task and by telling the agent to surface the `markdown` field. It does not describe size or pagination behavior for potentially long transcripts, which is a minor gap given an output schema 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?

Front-loaded scoping statement plus a routing sentence and a caveat, with no filler. The parenthetical is dense with unexplained in-house acronyms (SD/RD, SA, PM) but does convey the record's contents efficiently.

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 retrieval tool with annotations, a full input schema, and an output schema, the description covers what is returned, when it is empty, how to present it, and the sibling alternative. The unexplained acronyms and the absence of any transcript-length expectation are the remaining minor gaps.

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

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

Schema coverage is 100%, so both project_id and task_id are already documented in the schema, and the description adds nothing about scoping or what omitting task_id changes. It also leaves project_id unmentioned. Baseline 3 applies when the schema does the work.

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

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

The description names the specific resource and enumerates its contents (pre-implementation check, each round's SD/RD question, SA answer, PM decision), which is far more specific than the tool name alone. It also distinguishes itself from the nearest sibling by stating 'For the task's current state use get_task_status.' The only weakness is that the verb is implicit ('Call this and show `markdown`') rather than stated up front.

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 trigger ('whenever they ask what SA and SD/RD discussed') and names the alternative for a different need (get_task_status for current state). An agent has a clear routing rule without needing to infer anything.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond them: the fact that no mutating counterpart exists on this server and that changes happen via local console/CLI, which prevents wasted sibling searches. It does not discuss failure behavior for an unregistered project_id, so it is not exhaustive.

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 verb and scope, then the field enumeration, then two short clauses on mutability and the alternative. The long field list is dense but each item tells the agent what is retrievable; the only mild cost is that the enumeration dominates the sentence.

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

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

With one required parameter, 100% schema coverage, an output schema that carries the return shape, and annotations covering safety, the description only needs to establish scope and routing, which it does. The remaining gap is error/edge behavior for an invalid or unregistered project id.

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?

Only one parameter, and the schema already documents it fully at 100% coverage, including the pointer to list_projects for obtaining a valid id. The description adds no additional semantics about the id format or what happens when it is unknown, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Read a project's configuration') and then enumerates the exact fields returned: provider, model, effort, fallback per role, language, test_command, runtime, meeting_mode, evaluation_engine, workflow, review_gate, role names/avatars, read roots. This is far more precise than the name alone and separates it from siblings like get_context or preview_role_prompt.

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 rules out a class of use ('this server has no tool that changes settings, they are set with the local console or CLI'), which stops an agent hunting for a setter, and names preview_role_prompt as the alternative for inspecting what a role would actually be sent. It does not explicitly contrast with get_context or explain when settings-reading is warranted versus other context tools, so it stops short of a full when/when-not map.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; the description still adds real value by clarifying that only the hash is returned and never file content, which prevents an agent from using this as a read. It does not discuss failure modes (e.g. oversized or missing files), though the schema covers the 2 MB limit.

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: the first front-loads what is returned and why, the second covers the read-only/hash-only behavior and the alternative. No filler and nothing redundant with the 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?

For a simple two-parameter lookup with full schema coverage, complete annotations, and an output schema that documents the return value, the description supplies everything else an agent needs: the purpose, the hash-only behavior, and the sibling alternative.

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

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

Schema description coverage is 100%, with both path and project_id documented in the schema (including the 2 MB limit and the list_projects origin of project_id). The description adds no parameter-level meaning beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (get the {path, sha256} reference of one project file) and names the downstream use (citing as evidence in a ContextPatch via source_document_refs). It also explicitly distinguishes itself from read_workspace, so an agent can route between the two without opening either schema.

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

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

Gives clear when-to-use context (cite a file as evidence) plus an explicit alternative for the adjacent need: 'Use read_workspace to read a file's text.' It stops short of stating when this tool is unnecessary, e.g. that no reference is needed if the file is not being cited, so it is strong but not fully 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description still adds real behavioral context beyond the annotations: the emptiness precondition tied to evaluate_task and the inclusion of every kept re-evaluation version, which shapes what an agent should expect back.

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 purpose and payload, then the emptiness caveat, then sibling routing — an effective order with little waste. Minor redundancy: 'Never affects the task's own state' and 'Read-only' restate the same idea already carried by 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?

For a read tool with an output schema and fully documented parameters, the description covers purpose, preconditions, and alternatives adequately. The remaining details (pagination, exact report shape) are handled by the output schema, though the emptiness condition could be stated more precisely.

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

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

Schema description coverage is 100%, and the schema itself explains role filtering, the task_id default to the current workstream task, and project_id. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource: reads the task's Evaluation Engine reports, and enumerates the payload (quality_score, task_status, disagreements) plus kept re-evaluation versions. It is clearly distinguishable from evaluate_task, which creates those reports.

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 routes the agent: use evaluate_task to create reports, get_agent_reliability for cross-project track records, and notes the tool returns empty unless evaluate_task was called. Both the when and the when-not are 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 and destructiveHint=false, so safety is covered; the description adds ordering (oldest first), payload composition (raw agent report, immutable handoff package, options, observed evidence), and relative size versus get_task_status. It stops short of pagination, limits, or truncation behavior for what is described as a large response.

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 payload contents, then the routing alternatives. Dense but every clause carries information; the multi-clause sentence listing record components is slightly heavy but not 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?

An output schema exists and the description still declares what the record contains, its ordering, and its relative size versus a sibling, which is what an agent needs to decide to call it. Nothing material is missing for a 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 100% and both parameters are documented there, including the 'omit task_id to use the current workstream task' default, so the baseline is 3. The description adds only a loose hint about execution_id lookup and does not clarify parameter meaning beyond the schema.

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

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

States a specific verb and resource ('Read the full, unsummarized record of every execution of a task') plus scope details (oldest first, raw report, handoff package, host-observed evidence). It explicitly contrasts with get_task_status and get_task_evaluations, so an agent can pick it without opening sibling schemas.

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

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

Gives both when-to-use ('audit what an agent actually did', 'look up an execution_id') and when-not-to-use with named alternatives ('for the current state use get_task_status, for scored quality get_task_evaluations'). No inference required.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value beyond them by labeling the call 'cheap' (a cost hint an agent can use for polling decisions) and describing it as a point-in-time snapshot with a defined payload. It stops short of saying anything about event-log size or truncation, which is the one behavioral detail left 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?

Four sentences, no filler, and the core capability plus its payload are front-loaded before the alternative routing. The payload enumeration is dense but each item earns its place by telling the agent what it can inspect without a second call.

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 an output schema present, the description does not need to document return shapes, and it correctly spends its budget on capability, cost profile, and sibling routing instead. For a two-parameter read tool this is complete enough that an agent can call it correctly 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 description coverage is 100% and the task_id description already explains the 'omit it to get the current workstream task' default and when to pass a historical id. The description adds no parameter guidance beyond that, so this sits at the baseline 3 where the schema does the work.

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 where one task stands right now') and enumerates exactly what comes back: state, every execution with id/role/status/error, the event log, and a brief with progress, waiting_on, workflow, pending_dispatch. That level of specificity is enough to separate it from get_task_result and get_task_usage 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 use case ('call it to decide the next step') and then routes to three named alternatives with the condition that selects each: wait_for_task for blocking, get_task_result for agent reports and evidence, get_task_usage for token usage. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior that annotations cannot express: unavailability is reported as available=false with a reason and is never coerced to zero, which prevents a common misreading of the output. It does not discuss pagination or execution ordering, but with an output schema present that gap is minor.

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, front-loaded with the core action and ending with the sibling routing hint. The opening 'Read, per execution of a task' is slightly awkward phrasing but 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?

With only two parameters, full schema coverage, and an output schema that carries the return shape, the description covers everything an agent needs: what is returned conceptually, the unavailability semantics, and which sibling to use instead. Nothing material 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 100%, and the task_id parameter already documents the important default behavior (omit it to use the project's current workstream task; pass it only for historical tasks). The description adds no parameter-level meaning of its own, so the baseline of 3 applies.

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

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

States a specific verb and resource: it reads, per execution of a task, whether a local CLI was invoked and the token usage reported by that CLI. It is clearly distinguishable from sibling reporting tools because it explicitly names get_task_result as the tool for the reports themselves.

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?

Names the alternative (get_task_result) and the boundary between them: usage data here, report content there. It also flags the ChatGPT web execution case as an example of when usage is unavailable. It lacks explicit 'do not use this when' framing beyond that single alternative, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is partly given; the description still adds real context by listing what is returned (approval status with the local approval command while pending, and the application receipt once applied) and by stating it never mutates approval state. It stops short of covering errors, e.g. what happens for an unknown or already-applied edit_id.

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 scope statement is front-loaded, and the two sibling redirects at the end are compact and useful. The middle clause runs long as a single comma-chained list of return fields, which is dense but not 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 two-parameter read tool with full schema coverage, an output schema, and annotations covering the safety profile, this is complete: an agent knows what it fetches, what it returns, that it is side-effect free, and which sibling to use instead.

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

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

Schema description coverage is 100% and both parameters are documented there (including the EDIT-/BATCH- id format), so the schema carries the burden. The description's enumeration of target path, diffs and hashes describes return values rather than adding meaning to edit_id or project_id, so it adds no parameter-level guidance beyond the schema.

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

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

Names a specific verb (read) and a precisely scoped resource (one direct edit of the project's original files, or a multi-file batch), then enumerates the payload: target path, diffs, before/after hashes, approval status, application receipt. It is immediately distinguishable from get_approval_status and get_task_result, which it names.

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 routes the agent away from two siblings with their selecting conditions: 'For task plan approvals use get_approval_status; for a task's own file writes see get_task_result.' It also forecloses a misuse ('it never approves anything'), so when-to-use and when-not-to-use are both covered.

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

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

Annotations already establish that this is a safe read-only operation with no open-world or destructive behavior. The description adds useful behavioral context: it returns only operator-enabled tools, includes tool descriptions and input schemas, and warns that starting a server can take several seconds.

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 compact and front-loaded: it first defines the returned resource, then explains the next action, then gives a latency caveat. Every sentence contributes useful information without repetition.

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

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

For a simple read-only listing tool with a complete input schema, existing output schema, and annotations covering safety, the description provides enough context about content, follow-up invocation, and latency. No critical invocation detail 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?

The single required parameter is fully described in the schema as the registered project id returned by list_projects. The description mentions 'for this project' but adds no syntax, format, or validation detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the resource and scope: local MCP servers installed for a specific project, limited to operator-enabled tools with their descriptions and input schemas. It also distinguishes the listing action from the follow-up invocation tool by naming call_installed_mcp_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?

Usage is clear: use this tool to inspect installed local MCP servers, then call one via call_installed_mcp_tool. It does not explicitly cover when not to use it or list alternative discovery tools, but the intended workflow is easy to infer.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-obvious behavior beyond that: it takes no input and it never lists deleted projects, which prevents a wrong inference that the list is exhaustive of all historical projects. It stops short of saying anything about ordering or scale.

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 purpose, then usage, then an edge case, with no filler marketing language. Slightly longer than strictly necessary, but each sentence carries distinct 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 zero-argument, read-only list tool with an output schema present, the description covers purpose, usage precedence over other tools, and the deleted-project exclusion. Nothing an agent needs to call it correctly is missing.

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

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

There are zero parameters, so the baseline is 4. The description confirms the zero-argument nature ("takes no input"), which is a small but real reinforcement rather than a restatement of a rich 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 ("List every project the operator has registered with ccc-mcp") and names the payload returned (id and root folder). It explicitly contrasts with the sibling bootstrap_project, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit ordering instruction ("Call it first to learn a valid project_id for every other tool") and names the alternative for the deeper case (bootstrap_project to inspect one project). Both when-to-use and the routing alternative are spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it explains the selection-policy semantics, states that ccc-mcp (not the agent) chooses in 'fixed'/'auto' modes, and instructs the agent to tell the user which workflow it chose and why.

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

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

It is front-loaded with what the tool returns, then moves to the selection guidance, so every sentence carries operational value. The prose is slightly dense and the nested clauses about modes are a touch awkward, but 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 read-only, single-parameter listing tool with an output schema and full annotation coverage, the description covers the remaining gap: what the selection modes mean and which tool consumes the chosen id. Little else is needed, aside from an explicit statement of when not to call it.

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 a single parameter with 100% schema coverage, and the schema already explains project_id as the id returned by list_projects. The description adds only that workflows are scoped to a project, so it does not meaningfully extend parameter meaning beyond structured data; baseline 3 applies.

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

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

The description names a concrete verb+resource implicitly (list workflows for a project) and enumerates exactly what each entry contains: id, name, ordered steps, which is selected, and workflow_selection. That specificity lets an agent distinguish it from settings-oriented siblings like get_project_settings or list_projects without opening schemas.

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

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

It gives explicit decision rules tied to the workflow_selection value: when 'pm', pick the workflow that fits the task and pass its id to start_project_request; when 'fixed' or 'auto', do not choose. What's missing is a direct statement of when to call list_workflows itself versus other discovery tools, though the routing to start_project_request is clear.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the bar is lower, yet the description still adds real behavior: single-level listing, name sorting, has_more paging, and that credentials and managed metadata are hidden from results. That last point materially shapes what the agent should expect in the output.

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 opens with what the tool returns, then the paging hint, then the safety/filtering note, then the sibling routing rule and limits. Every sentence adds distinct information with no restatement of the 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 read-only listing tool with an output schema that already documents return shape, the description covers the remaining gaps an agent needs: scope (single level, within root), paging, hidden entries, and the handoff to read_workspace.

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

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

Schema coverage is 100%, and each of the six parameters is documented in the schema itself, including path, limit/offset and root_id semantics. The description only alludes to 'one folder' and 'the chosen root' without adding syntax or constraints beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource plus scope details: 'List the entries of one folder (single level, sorted by name) as path plus a directory flag, with has_more for paging.' It also distinguishes itself from the sibling read_workspace by noting it never reads file contents.

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

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

Explicitly routes the agent: 'Use it to find files, then read_workspace to read one,' and adds a negative constraint that it cannot list outside the chosen root. It stops short of explaining when to pick each root_id variant (project vs worktree vs operator-granted root), leaving that to the schema.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description still adds real value by asserting fidelity — the text comes from the same code a real dispatch uses — and by naming what is included (provider, write-file permission). That is meaningful context an agent could not infer from the annotations alone.

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

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

Three short sentences, front-loaded with the core action and the no-side-effect guarantee, each carrying distinct information. The only minor waste is restating the role set that the schema already lists.

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?

An output schema exists, so return values need no explanation; the description covers purpose, side-effect posture, build fidelity, and a pointer to the related settings tool. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the role examples. The description's role list (SA/SD/RD/SD-RD/REVIEW) largely duplicates the schema's enumeration and adds no format or constraint details, so baseline 3 applies.

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

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

States a specific verb and resource: 'Preview exactly what a role ... would be sent given current settings, without dispatching anything.' The no-dispatch clause cleanly separates it from dispatch_agent, so an agent can tell the two apart without opening either schema.

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

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

Gives a clear context of use (inspecting what a dispatch would contain before committing) plus an explicit companion call: 'Use get_project_settings to see the configuration behind it.' It stops short of naming an explicit when-not-to-use case beyond the implied 'don't use this to actually dispatch', so it is not a full 5.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false; the description goes further by naming the four rejection conditions (stale base_context_version, unknown or immutable sections, secrets, missing semantic_review_ack) and by stating the return payload is patch_id plus a unified diff. That is real behavioral disclosure an agent needs before calling.

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 short sentences, each carrying distinct information: purpose, return value, failure modes, workflow. Front-loaded correctly. Minor deduction for the clipped, list-like phrasing of the rejection sentence, which reads as fragments rather than prose.

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?

An output schema exists, so the description is not obligated to explain return values, yet it still names the key return (patch_id, diff) that drives the follow-up call. Combined with rejection conditions and next-step routing, nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents patch fields including base_context_version and semantic_review_ack, making the baseline 3. The description earns a small bump because it adds rejection semantics for those fields and flags 'secrets' as a failure mode that the schema does not mention.

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 precise compound action: validate a ContextPatch against the current Context and store it as a proposal, with the explicit scope boundary 'nothing is applied yet'. This clearly separates it from the sibling commit_context_patch, which is named later.

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 workflow: gather inputs with collect_context_updates, propose here, then call commit_context_patch with the returned patch_id to apply. The when-not (nothing applied at this stage) is stated up front, so an agent cannot confuse the propose step with the apply 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?

Beyond the readOnly/destructive annotations, it discloses the concrete constraints that shape behavior: files over 2 MB and non-UTF-8 files are refused, credentials are redacted with a redacted=true signal, and managed metadata is excluded. Those are exactly the surprises an agent would otherwise hit at call time.

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 refusals and redaction constraints are front-loaded and each sentence carries real information. The only redundancy is the standalone 'Read-only' sentence, which restates readOnlyHint=true from the annotations and could be dropped.

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 windowed file-read with six parameters, the description covers access constraints, redaction, return shape, and the follow-on handoff to write_task_file; the existing output schema handles the exact return structure. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so every parameter including root_id's root choices and execution_id's worktree dependency is already documented in the schema. The description adds only the start_line/total_lines windowing notion, which the schema's own defaults largely convey; baseline 3 applies when the schema carries the load.

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 a window of one UTF-8 text file') plus exactly what is returned (content, sha256, start_line, total_lines). It also explicitly separates itself from list_workspace (finding files) and get_source_reference (hash only), so an agent can pick it out of a crowded sibling 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?

Names two alternatives with the condition that selects each: list_workspace for discovery and get_source_reference for hashes only. It also gives a forward-looking usage rule — keep the sha256 to pass as expected_sha256 to write_task_file — which links this read to the subsequent write.

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 a non-read-only, non-destructive, closed-world mutation; the description adds the key behavioral guarantee beyond that, namely that it only touches executions provably not running, which is what justifies destructiveHint=false for a tool that clears state. It does not state idempotency or the no-op case when nothing is orphaned, so it is not fully exhaustive.

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?

A single dense sentence that front-loads the action and scope before the routing clauses; every clause carries information. It is slightly run-on with the nested parenthetical and two sibling references, 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?

For a one-parameter tool with full schema coverage, annotations, and an output schema, the description supplies everything needed: scope, safety guarantee, trigger condition, and alternatives. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100% and the single project_id parameter is already documented as the id returned by list_projects, so the schema carries the semantics. The description adds nothing about the parameter, which is acceptable at this coverage 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: clearing executions stuck in QUEUED/RUNNING that have no live worker holding their lock. The parenthetical failure mode (worker crashed or never started) narrows the scope further, so an agent can distinguish this from sibling maintenance tools 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 condition — call when get_task_status.brief.progress.orphaned is true — and names two alternatives with the conditions that select them: resume_pending_dispatch for an interrupted advance_project, cancel_task to abandon a task. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation and safety profile is known; the description adds the crucial versioning semantics ('kept as a new version, never overwriting the previous one') and the feature-flag prerequisite, both beyond structured fields. It stops short of describing cost, latency, or when the new version becomes visible, which keeps it at a 4.

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

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

Three short sentences, each doing distinct work: action plus non-destructive guarantee, parameter discovery, then prerequisite and alternative. Zero filler and the distinguishing 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?

With an output schema present and annotations covering safety, the remaining agent needs — prerequisite, ID provenance, task-level alternative, and the non-overwrite guarantee — are all covered. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds provenance for execution_id by naming the two tools that surface it. It says nothing about task_type, whose grouping purpose is 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?

States a specific verb and resource ('Force a fresh Evaluation Engine pass over one specific execution') and immediately scopes it to a single execution, which differentiates it from the task-level sibling evaluate_task. An agent can pick between the two without opening either schema.

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

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

Gives explicit routing: 'to score a whole task use evaluate_task', a prerequisite ('Requires evaluation_engine enabled'), and how to obtain the required execution_id via get_task_evaluations or get_task_result. Both the when and the when-not are present.

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 say not-read-only and not-destructive; the description adds the real behavioral payload — that this call dispatches the next clarification round or the actual implementation automatically, i.e. it has far-reaching downstream effects. It also discloses the prerequisite state field that gates the call and the human-escalation branch, which annotations could never encode.

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 gating condition, then the branch rule, then the exclusion — a sensible order with no filler sentences. It is dense with dotted field paths (get_task_status.brief.waiting_on, brief.clarification.escalation), which is efficient for a machine reader but makes the prose heavy; a small amount of that 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?

Return shape is covered by the output schema, safety by annotations, and all three parameters by the schema, so the description's remaining job is preconditions and branching, which it does well. The one gap is failure behavior: it never says what happens if the task is not actually waiting on PM_CLARIFICATION_DECISION or if the decision is rejected.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds sourcing guidance the schema lacks: the decision content comes from brief.clarification.pending_pm_decision (question plus SA's recommendation) in the auto_pm case, or from the human's actual reply in the ask_user case. It does not add format or length guidance for 'decision' beyond what the schema already says.

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 ('PM resolves a Meeting Mode clarification SA escalated with pm_decision_required') plus the exact state predicate that must hold (get_task_status.brief.waiting_on == PM_CLARIFICATION_DECISION). It also names the siblings it must not be confused with (dispatch_agent, advance_project), so an agent can separate it from the surrounding clarification/gate tools 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 two-branch routing rule: when brief.clarification.escalation == 'ask_user' the agent must present the question to the human and wait for a real reply before calling; when it is 'auto_pm' the PM may decide immediately. It also supplies an explicit exclusion ('never call dispatch_agent or advance_project for this instead'), which is exactly the when-not guidance most definitions omit.

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 cover the safety profile (mutation, non-destructive, non-open-world), and the description adds genuinely useful behavior: gate state prerequisites, that 'stop' cancels the task, that 'retry' sends work back once more, and that the next step dispatches automatically after the call. It does not describe the response payload or what happens to in-flight work on 'stop', so there is remaining behavioral ambiguity despite good added context.

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

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

Information-dense and front-loaded: the trigger condition comes before the decision vocabulary and the escalation caveat. The embedded schema paths and the ragged indentation make it slightly harder to scan than it needs to be, 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 state-dependent mutation with an output schema already present, the description supplies everything an agent needs to call it correctly: how to detect the gate, where to read the reason and findings, how to interpret escalation, and what each decision does downstream.

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

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

Schema description coverage is 100%, so the baseline is 3; the description restates the decision values in nearly the same words as the schema and names the source of task_id and the pending_decision fields without adding format or edge-case semantics for 'note'. It adds decision-authority context, but that is primarily usage guidance rather than parameter meaning.

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

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

Specific verb and resource: 'PM decides a workflow review gate that ran out of rounds or rejected the approach', with the exact precondition stated (get_task_status.brief.waiting_on == PM_FLOW_DECISION). An agent can distinguish this from resolve_clarification or review_changes 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 gating rule: check brief.workflow.pending_decision.escalation first, where 'ask_user' means surface findings to the human and wait, and 'auto_pm' means decide immediately then inform the user. It also spells out what each decision value commits to, so both when-to-call and which-value-to-pass are 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?

Annotations declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing idempotency (safe to call repeatedly) and exactly what side effects will not recur (never re-submits or re-commits Context). That is precisely the reassurance needed for a non-destructive state-changing recovery tool, and it does not contradict 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?

Three sentences, each load-bearing: what it repairs, exactly when to call it versus the alternative, and its safety contract. The verb and precondition are front-loaded, 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 recovery tool with an output schema and full schema coverage, the description supplies everything else an agent needs: the detection signal, the forbidden alternative, the interruption causes, and idempotency. Nothing required to decide or safely invoke it 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 100%, with project_id explained as the id returned by list_projects and task_id as an optional scoping argument, so the schema already carries parameter meaning. The description adds trigger-state context but no additional syntax, defaults, or scope behavior for task_id, so the baseline 3 applies.

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

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

States a specific verb and scope: finishing an advance_project round interrupted after Context was committed but before the next role was confirmed dispatched. It names the exact sibling it must not be confused with (advance_project with a reconstructed patch), so an agent can select it 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 an explicit trigger condition (get_task_status.brief.waiting_on == DISPATCH_RETRY_NEEDED, equivalently brief.pending_dispatch is not null) and an explicit exclusion with the alternative tool to avoid. It also enumerates the failure causes (crash, worker spawn failure, transient VersionConflict) that lead here.

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 it discloses the critical async behavior ("returns right away with the new execution and does not wait for a verdict") and the side-effect boundary ("The reviewer never edits files"). The readOnlyHint=false annotation is consistent with a tool that enqueues a new execution, so no conflict arises with the "read-only REVIEW" phrasing.

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 its synchronous/asynchronous contract are front-loaded in the first two sentences. Every remaining sentence carries distinct information: the no-file-edit guarantee, the follow-up tool chain, and the workflow-vs-manual condition.

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?

An output schema exists, so return values need not be enumerated, yet the description still notes that the new execution is returned. Combined with the follow-up path and side-effect boundary, nothing an agent needs to call and correctly sequence this tool is missing.

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

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

Schema coverage is 100%, with task_id, project_id, instruction, and context_version all documented in the schema, including the version-conflict consequence of a stale context_version. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

"Queue one independent, read-only REVIEW of a task's changes, run by whichever provider the project configured for REVIEW" gives a specific verb (queue), resource (review of task changes), and scope (one, independent, provider-configured). It is clearly distinguishable from dispatch_agent and the normal workflow, which do not describe an additive review request.

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 explicitly when to call it ("call this to request an additional review") and when it is normally unnecessary ("The workflow normally dispatches REVIEW itself after implementation"). It also routes the agent through the follow-up sequence: wait_for_task or get_task_status, then get_task_result.

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 by disclosing a real side effect (starting a new round invalidates the prior plan approval), a conditional-parameter rule tied to project workflow_selection, and two post-call obligations: acting immediately on a non-null action_required rather than ending the turn, and prefixing the user reply verbatim with meeting_mode_notice.text. These are exactly the non-obvious behavioral traits an agent cannot derive from readOnlyHint=false / destructiveHint=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?

Front-loads the core action, then the scoping rule, then the prohibitions, then the result-handling rules — a sensible ordering where each sentence carries distinct information. It is dense and the irregular indentation/line wrapping makes it slightly harder to scan than a clean bulleted structure would.

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?

An output schema exists, so return-value shapes need not be explained, and the description nonetheless covers the two result fields that require caller action (action_required, meeting_mode_notice). Combined with the workflow-selection rule and the turn-continuation contract, an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the workflow_selection='pm' condition, which the description largely restates. The only added meaning is the instruction to call list_workflows before passing `workflow`; acceptance, project_id, requirement, and wait_seconds receive no extra description-level semantics.

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 ('Begin a NEW authorized project change, dispatch the workflow's first step') and immediately bounds scope with 'NEW', separating it from continuation/inspection operations. An agent can distinguish this from siblings like advance_project, resume_pending_dispatch, or get_task_status without opening any schema.

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

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

Explicitly states the negative case: never use it to continue, retry, recover, or inspect an existing task, and explains the consequence (starts a new round, invalidates prior plan approval). It also gives a prerequisite (call list_workflows first) and the condition under which `workflow` matters. The one gap is that it never names the specific sibling tools an agent should use instead for continue/retry/inspect, leaving that mapping 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?

Annotations already declare a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds behavior the annotations cannot convey: the backend auto-advances the workflow, the response carries workflow/action_required, and the agent should keep working in the same turn. Missing detail on what happens to an already-submitted report or whether it can be resubmitted.

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 primary action front-loaded and the advance_project exception clearly separated by parentheses. No filler, though the line-wrapped parenthetical with backend jargon (auto_advanced) is denser than necessary.

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 submit tool with an output schema present, the description covers the essential decision logic: an agent knows what is saved and how to continue after the call. The remaining gap is the report object's semantics, which sits in neither the schema nor the description.

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 75%, so project_id and execution_id are already documented with pointer hints (list_projects, get_task_result), and wait_seconds' default and early-return behavior is described in the schema itself. The description adds only loose framing for the report payload ('raw report, context suggestions and host-observed file evidence'), leaving the nested AgentReport fields such as needs_revision, simulated, and tests unexplained. That is near the schema-driven baseline.

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 concrete action plus payload scope: finishing an active role and saving the raw report, context suggestions, and file evidence. It also names the sibling it replaces in the auto-advance case (advance_project), which lets an agent distinguish it without opening schemas. Slightly muddied by the phrase 'ChatGPT role', which is jargon an agent must interpret.

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 conditional rule: when auto_advanced=true the agent must not call advance_project and should follow the returned workflow/action_required in the same turn. That is real routing guidance. It does not cover the inverse case (what to do when auto_advanced is false) or when this tool is inapplicable.

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, destructiveHint=false and openWorldHint=false, and the description adds real behavioral context on top: this role never writes files, Meeting Mode resumes automatically, and the caller must immediately act on a non-null action_required rather than ending its turn. That is exactly the kind of follow-up-loop disclosure annotations cannot carry. The one weak spot is a mild tension between "Read-only role" and readOnlyHint=false, which could momentarily confuse an agent about whether the call mutates state.

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

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

The purpose statement is front-loaded and each subsequent sentence carries an operational rule (auto-continuation, action_required, meeting_mode_notice prefix). Some wording is dense, notably the nested parenthetical about expected_report_fields and the stray line breaks, but nothing is truly 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 submission tool inside an automated workflow this is close to complete: it states the precondition, the non-mutation of files, and how to handle the two key response fields, and an output schema exists so return values need not be restated. The gaps are the absence of guidance on wait_seconds/settling behaviour in prose and no mention of failure or invalid-handoff handling.

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 75% and the ClarificationRequest sub-object carries its own description, plus project_id, execution_id and wait_seconds are all documented in the schema, so the structured data does most of the work. The description's contribution is naming the expected report fields, which does not add much beyond the nested schema definition and adds nothing about wait_seconds or the blocking behaviour of the call. Baseline 3 is appropriate.

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

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

"Finish an active ChatGPT Meeting Mode SD/RD check" gives a specific verb plus a named workflow stage, and the parenthetical (expected_report_fields are blocking_question, no_blocking_question, rationale) pins down exactly which payload this tool submits. It implicitly separates itself from submit_agent_report / submit_clarification_response by tying the call to a Meeting Mode SD/RD handoff, though it never names 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?

Usage is implied through the precondition (there must be an active check whose expected_report_fields match), and the description gives firm post-call directives for action_required and meeting_mode_notice. However, it gives no explicit when-not guidance and does not distinguish this from resolve_clarification, submit_clarification_response, or submit_agent_report, so an agent must infer which submission tool is correct from context alone.

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, it discloses meaningful runtime behavior: Meeting Mode continues automatically after the call, action_required must be acted on immediately without ending the turn, and meeting_mode_notice.text must lead the user reply verbatim. The only weak spot is "Read-only role", which sits awkwardly against readOnlyHint=false and could confuse an agent about whether this call mutates state.

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

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

Purpose is front-loaded, then the conditional directives follow in priority order. Though wrapped across lines and jargon-dense, every sentence carries an actionable instruction 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?

An output schema exists, so return values need not be restated, and the workflow-continuation semantics are covered well. However, the enum semantics of response_type, error/failure behavior, and the meaning of the "read-only role" phrase relative to the mutation annotations are left unaddressed for a 4-parameter submission 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 coverage is 75% and project_id, execution_id and wait_seconds are already documented in the schema. The description adds the useful link that the report's expected fields are response_type and content, but explains nothing about choosing between confirmed, recommendation and pm_decision_required.

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 action on a specific resource: finishing an active ChatGPT Meeting Mode SA answer, and identifies the expected handoff payload (response_type, content). It never distinguishes itself from near-name siblings like submit_clarification_request or resolve_clarification, and the jargon ("SA answer", "handoff") assumes prior context.

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

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

It implies the trigger condition (there is an active handoff awaiting this answer) and gives strong post-call guidance about following the returned workflow, but it never states when to prefer this over submit_clarification_request or resolve_clarification, nor any when-not conditions.

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 cover the safety profile, yet the description goes further: it discloses the actual mechanics (re-hashing cited source files, comparing generated docs against the stored version for projection drift, verifying evidence artifacts) and the issue format (path + reason). It also states an important limitation — 'proves provenance only, not that the content is correct' — which prevents over-trusting a passing result.

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 purpose and return shape, then mechanism, then safety/when-to-use, then scope caveat. Every sentence adds distinct information with no redundancy.

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

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

An output schema exists, but the description still names the return keys, which is helpful rather than redundant. For a single-parameter read-only validation tool, the description covers what it does, when to run it, and what its result does and does not prove.

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

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

Schema coverage is 100%, so the single project_id parameter is already fully documented in the schema. The description adds no syntax or format detail about project_id, so this sits at the baseline where the schema carries the load.

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 ('Check that the project's Context is intact') plus the exact return shape {valid, issues, context_version}. It is clearly separable from siblings like get_context (read content) and propose_context_patch (mutate), since this one only verifies integrity.

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?

'Read-only and safe to run any time, for example before proposing a ContextPatch' gives a concrete trigger and prerequisite context. It stops short of explicit exclusions or naming the alternative tool it replaces (e.g., get_context for reading content), so it is clear but not fully routing.

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 read-only/non-destructive safety, but the description adds the blocking/long-poll behavior, the early-return conditions (terminal states, failures, decisions requiring user input), and required post-call protocol for action_required and meeting_mode_notice. That is substantial behavioral context beyond what the structured fields declare.

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

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

The purpose and the get_task_status alternative are front-loaded, and every block carries operational meaning. Minor waste from overlapping instructions about not ending the turn (timed_out/must_continue_in_this_turn vs. action_required) and from ragged indentation that makes the text look longer than it is.

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?

An output schema exists, so return-value documentation is unnecessary; the description instead names the specific result fields that drive downstream behavior (action_required, meeting_mode_notice, timed_out). For a blocking poll tool this is complete enough to invoke and act on correctly.

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

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

Schema description coverage is 100% and the schema itself explains omitting task_id to use the current workstream task and the timeout range. The description adds no additional parameter guidance, so the baseline 3 for fully documented schemas is appropriate.

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

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

States a specific verb and resource ("wait for background Agent work to settle") and immediately frames the mechanism as a "Read-only long poll." It also explicitly contrasts itself with get_task_status for an instant snapshot, so an agent can distinguish it from siblings 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 when-to-use alternative ("Use get_task_status for an instant snapshot instead") and a concrete when-not-to-stop rule: if timed_out or must_continue_in_this_turn is true, do not end the turn. It also states which outcomes cause an early return, so the agent knows what conditions end the wait.

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 by naming concrete rejection modes: secret-like content, a stale Context version, and a change that would drop original Python comments, plus before/after SHA256 receipts. The only soft spot is that 'replaces the file' sits slightly against destructiveHint=false, but the expected_sha256 guard and comment-preservation rule explain the non-destructive framing rather than contradicting 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?

Four dense sentences, front-loaded with the action and refusals before the workflow pointers; nothing is filler. Minor deduction for the awkward line-wrapped formatting and the slightly compressed listing of rejection reasons, which reads as a run-on.

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 preconditions (approved plan, authorized execution), the failure modes, the concurrency contract, and the follow-up step, while an output schema exists so return values need not be spelled out. Nothing an agent needs to call this mutation safely 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 100%, so every parameter including expected_sha256 and its omit-to-create rule is already documented in the schema. The description's mention of reading with read_workspace to get expected_sha256 restates the schema rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Write one whole file in the authorized project through your running ChatGPT execution.' The whole-file (not patch) framing plus the explicit tie to an authorized execution cleanly separates it from read_workspace, propose_context_patch, and submit_agent_report.

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

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

Gives explicit when-not conditions ('SA and REVIEW executions are read-only and are refused') and the required surrounding workflow: read first via read_workspace to obtain expected_sha256, finish the role with submit_agent_report. An agent knows both the preconditions and the next step without inference.

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