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

Annotations already indicate readOnlyHint=true, and the description adds behavioral detail: results are ordered by blocking priority and include rationale, options, suggestion, and blocked/independent work flags. No contradiction with annotations.

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

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

The description is a single dense sentence with no filler, front-loading the core resource. However, it is a sentence fragment rather than a complete declarative statement, which slightly reduces clarity.

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 full parameter documentation, the description adequately covers the tool's purpose and return content. The only missing element is explicit usage context, which is more of a usage-guidelines concern. Overall complete for a read-only list 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 the baseline is 3. The description does not add any parameter-specific nuance; status filtering and sessionId semantics are left entirely to the schema.

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

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

The description identifies the resource as the decision queue and specifies its ordering (most blocking first) and content (why each matters, options, agent suggestion, blocked/independent work). It clearly implies a read-only retrieval operation, but lacks an explicit verb like 'returns' or 'lists'. It is distinguishable from sibling mutations by its focus on the queue.

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

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

No guidance is provided for when to call this tool versus alternatives such as request_decision or record_decision, nor any mention of prerequisites beyond the sessionId in the schema. The usage context is only implied by the resource name.

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 mark this as read-only with openWorldHint=false. The description adds useful behavioral context by specifying the exact content of the handoff and the ordering guarantee ('decisions needed (most blocking first)', 'ordered next actions'), which goes beyond the schema and annotations.

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

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

The description is one information-dense sentence followed by a short directive. It front-loads the core idea ('Exactly where to pick up') then enumerates the included content without repetition or 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 return structure does not need to be described in detail. The description covers the tool's purpose, content, ordering, and when to use it, while the input schema fully documents the single required parameter. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%: the single sessionId parameter is fully described as 'Session handle returned by start_session.' The description adds no parameter-level detail, but with full schema coverage 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?

The description makes the tool's purpose clear: return a comprehensive handoff summary including state, decisions, checkpoints, ready/blocked units, completed work, context, repository state, and next actions. It is distinct from siblings like get_session or get_phase because it packages the full handoff picture, though it does not explicitly name those alternatives.

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

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

The instruction 'Start DESK_MODE here' gives an explicit usage moment for this tool. It does not state exclusions or explicitly compare with get_session, get_work_graph, or get_session_report, but the context is clear enough for a capable agent.

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 readOnlyHint annotation already signals safety. The description adds value by detailing exactly what data is returned (goal, exit criteria, constraints, progress, project context), which is beyond the annotation. No contradictions.

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

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

The description is a single sentence that front-loads the key items returned. It is efficient and not overly verbose, though it lists several items in a way that could be seen as slightly dense.

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 getter with one parameter and an output schema, the description covers what the tool returns. It does not mention prerequisites like session existence or activeness, but that is likely handled by the output schema or error messages, so it is reasonably complete.

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

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

The single parameter sessionId is fully described in the schema (100% coverage), so the description need not elaborate. Baseline of 3 applies; the description adds no extra 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?

The description clearly indicates this tool retrieves phase-related information for a session: goal, exit criteria, constraints, progress, and project context. It is not a tautology and is distinct from sibling tools focused on sessions or work graphs, though it could be more explicit about the retrieval action.

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

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

No guidance is given on when to use this tool versus alternatives like get_session or get_work_graph. The description implies it is for inspecting a phase, but there is no explicit context for selection or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the list of inspected data fields, but it does not disclose staleness, caching, error behavior, or any prerequisites beyond what the schema provides.

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

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

The description is a single telegraphic sentence that front-loads the core content immediately. Every listed item adds information, and there is no filler or repetition of the tool name.

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

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

With an output schema present, one fully documented parameter, and read-only annotations, the description is sufficient for correct invocation. The only minor gap is not clarifying how this relates to get_session_report, but that falls under optional usage routing rather than essential invocation context.

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 input schema fully documents sessionId as the required session handle returned by start_session (100% coverage). The description adds no additional parameter semantics, 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?

The description names the specific resource ('one session') and the exact data returned: state, mode, budget, unit counts, in-flight units, and run history. This clearly differentiates it from siblings like list_sessions, start_session, and get_session_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?

The description implies use when inspecting a single session's current state, but it gives no explicit when/when-not guidance or named alternatives. A capable agent can infer the use case, but the routing is not made explicit.

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, so the description doesn't need to restate that. It adds useful context by listing the detailed contents of the report, which goes beyond the schema. However, it doesn't disclose any potential performance costs or whether the report is generated on demand, but it's a read-only operation so the burden is lower.

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

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

The description is a single, dense sentence that lists all the report contents without fluff. It is slightly long but packs useful detail, making it efficient. The key content list is front-loaded after 'Session report'. Every word contributes to explaining what the tool delivers.

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 the tool's complexity—it returns a rich report with many fields—the description enumerates all the key sections. The output schema exists and likely details the exact structure, so the description doesn't need to repeat that. The only minor gap is that it doesn't mention how to obtain the sessionId beyond the schema's pointer to start_session, but that's already 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?

The only parameter is sessionId, and its schema description ('Session handle returned by start_session.') fully explains its semantics. The description adds no additional information about the parameter, but with 100% schema coverage, 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?

The description clearly states the tool's purpose as fetching a session report and enumerates the specific content it includes (outcome, budget usage, completed work, etc.). It distinguishes it from tools like get_session, which likely returns basic session info, though it doesn't explicitly name a sibling for contrast.

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

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

The description implies that this should be used after a session has been started and when a detailed report is needed, but it does not explicitly state when to use it vs. alternatives like get_session or list_sessions. No guidance on when not to use it is provided.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context by explaining the graph contains derived readiness and enumerating root-cause kinds ('decision:', 'blocker:', 'failure:', 'cancelled:'), which goes beyond what annotations alone convey. No contradiction.

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

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

Two dense sentences with no filler; the graph contents are front-loaded and the filter options are presented compactly. Every clause adds information about what the tool returns or how to constrain it.

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 inspection tool with an output schema and fully documented parameters, the description covers the graph contents and filter choices sufficiently. It does not discuss ordering or pagination, but nothing in the annotations or schema signals that such details are required.

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 sessionId and filter, including the 'Default all' behavior. The description's 'Filter: all | remaining | ready | in_progress | done' restates the enum without adding new meaning, so it earns the baseline 3.

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 precise contents: 'Units with status, derived readiness and root causes..., plus dependency edges,' making it immediately clear this returns a graph snapshot. The title 'Inspect work graph' reinforces the verb-resource pair and distinguishes it from sibling tools like get_phase or get_session.

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

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

No explicit when-to-use or when-not-to-use guidance is given, and no sibling alternatives are named. The readOnlyHint and graph-centric wording imply this is the inspection tool, but the agent must infer the selection context rather than being told.

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 indicate readOnlyHint=true and openWorldHint=false, so the description does not need to reiterate safety. It adds value by disclosing the ordering (newest first), the included fields, and the default behavior of includeTerminal (via schema, but the description does not mention the default). The description does not contradict annotations. Given the annotations, a score of 4 is appropriate for going beyond them with ordering and filter details.

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

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

The description is a single sentence that is front-loaded with the primary purpose and then adds a usage hint. Every word is useful, with no redundancy or filler. It is concise and well-structured.

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

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

Given the tool's complexity (a simple list operation with 2 optional parameters), the description is sufficient. An output schema exists (though not shown in the prompt, it is indicated), so the description does not need to explain return values. The description covers what the tool does, how results are ordered, and when to use it. Minor gaps: it does not mention what happens if no sessions exist or how pagination works, but these are not critical for basic usage.

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 fully documents both parameters, including defaults. The description does not add any parameter-specific information beyond what the schema provides. Thus, a 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 tool 'lists recorded sessions' with a specific ordering (newest first) and included fields (state, budget, open decision counts). This distinguishes it from sibling tools like get_session, which likely retrieves a single session. The purpose is unambiguous and actionable.

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

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

The description says 'Use to find a session to inspect or resume,' which provides clear context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, though siblings like get_session or get_session_report are implied. This is a minor gap.

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 signal a non-read-only, non-idempotent operation, so the description is not required to prove mutation. It adds value by defining the state-transition semantics of each action and the critical rule that only 'stop' terminates an OUTSIDE_MODE run. No contradiction with 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?

Every sentence earns its place: the purpose, all four action semantics, call cadence, and termination rule fit in a compact description. The key claim is front-loaded and the action definitions are efficiently packed.

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 one documented parameter, a true output schema, and the action semantics explained, an agent has enough to call next_work correctly. Minor ambiguity remains around terms like 'dispatched units' and 'policy,' but these do not block correct invocation.

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

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

Schema coverage is 100% and the sole parameter sessionId is already described as 'Session handle returned by start_session.' The description adds no parameter-specific information, so it sits at the baseline for high schema coverage.

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?

Description opens with a clear, specific action: 'Re-evaluate the graph, budget and policy and claim the next work.' It then unpacks the four action values (execute, wait, plan, stop) with concrete meanings, which disambiguates it from lifecycle siblings like report_work and get_phase.

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 an explicit call condition: 'Call after every report_work.' It also clarifies the terminal condition: 'Only "stop" ends an OUTSIDE_MODE run.' It does not name alternatives or exclusions, so it isn't a 5, but the timing guidance 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 signal non-read-only and non-destructive. The description adds useful behavioral details: stopping the budget clock and preserving in-flight claims, plus optional handoff notes. This goes beyond the annotation baseline and enriches the agent's understanding of side effects, even though it doesn't cover auth or rate limits.

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

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

Two sentences with no redundancy. The core action is front-loaded, and behavioral details follow immediately. Every word earns its place; there is no filler or extraneous 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 the presence of an output schema, return values need not be explained. The description covers the essential behavior (pausing, budget clock, in-flight claims, handoff notes) and correctly restricts to active sessions. Missing details like error handling are minor for a state-change tool of this simplicity.

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 67%, so the baseline is 3. The tool description reiterates the purpose of the notes parameter ('Optional handoff notes'), which aligns with the schema's own description, adding little new meaning. The reason parameter remains undocumented in both places, so the description does not fully compensate for the coverage gap.

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

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

The description clearly states the action ('Pause an active session') and adds specific behavioral consequences ('Stops the budget clock and keeps in-flight claims'), which distinguishes it from siblings like resume_session and stop_session. The mention of handoff notes further clarifies its purpose without ambiguity.

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

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

The description implicitly indicates usage by describing the pause behavior (stops budget clock, keeps claims) which suggests a temporary halt compared to a stop. However, it does not explicitly state when to use this tool instead of alternatives like stop_session or resume_session, nor does it mention exclusions. Sibling context helps infer, but it falls short of explicit guidance.

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

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

Annotations only indicate non-readonly non-destructive flags. The description adds a behavioral effect ('Releases the units the decision gated') and a refusal condition, both of which go beyond the structured annotations. No contradiction 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?

Two sentences, with the primary purpose front-loaded and constraints/effects packed tightly afterward. Every clause adds information and there is no repetition or 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 available, return values need no explanation. The description covers the essential call conditions, refusal context, and side effect, making it complete enough for correct invocation.

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

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

Schema coverage is 67%, so the schema already defines most parameters. The description clarifies the choice-vs-withdraw relationship ('or withdraw') which adds meaning beyond the individual parameter descriptions, but it does not otherwise deepen the parameter 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?

The description names a specific action ('Record') on a specific resource ('a decision made by a human') and immediately distinguishes the alternative use case ('withdraw a question'). It clearly separates this from sibling tools like request_decision (which asks) and get_decisions (which reads).

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

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

The description gives a decisive usage rule ('Only call with the human's explicit answer') and a hard precondition ('Refused while an OUTSIDE_MODE run is active'). It does not explicitly name when to prefer this over request_decision, but the sibling names and the wording make that inference straightforward.

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 are minimal (readOnlyHint false, idempotentHint false, destructiveHint false), so the description adds value by explaining the behavioral nuance: 'Completed with failing checks counts as a failed attempt' and that reporting does not end the session. It also mentions required evidence for completed and blocker for blocked, which are behavioral constraints beyond the schema.

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

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

The description is two sentences with no fluff. It front-loads the primary action and outcome types, then adds the crucial workflow instruction. Every word contributes to understanding the tool's purpose and use.

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

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

The description covers the core purpose and the required next step (next_work). It doesn't detail every parameter, but the schema covers that. It also lacks explicit mention of the sessionId requirement, but that is standard. The output schema exists, so return values need no explanation. The description is sufficient for an agent to know when and how to call this 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 88%, so the schema already documents most parameters. The description adds semantic clarity for the completed outcome: 'Completed with failing checks counts as a failed attempt,' which clarifies how the validation object's 'passed' field interacts with the outcome. It also highlights that completed requires validation evidence and blocked requires a blocker, reinforcing schema descriptions.

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 tool's function: 'Report a claimed unit' with a specific set of outcomes (progress, completed, failed, blocked, released). It distinguishes itself from siblings like next_work by naming the next step explicitly and by defining what each outcome means. The verb and resource are unambiguous.

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

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

The description gives clear guidance on the follow-up action: 'Then call next_work: a finished unit never ends the session.' This implies the tool is for reporting status and that the session continues. It doesn't explicitly state when not to use it, but the context is sufficient for an agent to know this is the reporting action in a workflow.

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

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

Discloses important behavioral traits beyond annotations: affected units wait while others continue, it returns impact and independent work, and it does not block or wait for an answer. This is substantial non-obvious behavior that helps the agent understand side effects and asynchronous semantics.

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

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

Four tight, information-dense sentences with no filler. Key behavioral distinctions are front-loaded: queueing, no guessing, partial waiting, and non-blocking behavior.

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

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

Given an output schema and 75% schema parameter coverage, the description covers the important behavioral context: what is blocked, what continues, and what is returned. It could add a bit more guidance on how checkpoint and affectedUnitIds relate to the waiting behavior, but the essential calling context is clear.

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

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

Schema description coverage is 75%, so the schema already documents most parameters. The description adds general context about human-judgment categories but does not enrich individual parameters like options, checkpoint, or recommendation beyond what the schema provides. 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 ('Queue') and resource ('a question that needs human judgment'), with a clear scope of categories. The description distinguishes this from sibling tools like record_decision by emphasizing it queues a question rather than recording an outcome.

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 condition for use: when human judgment is needed, and instructs 'Never guess instead.' It clarifies non-blocking behavior and partial waiting, but does not explicitly name alternative tools or exclusions, so it stops short of a 5.

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

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

With annotations already indicating this is not read-only and not idempotent, the description adds useful behavioral detail: it recovers in-flight units to pending with their checkpoints and returns the handoff. It doesn't cover auth or failure side effects, but it goes beyond annotation data.

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 four short, focused sentences that front-load the main purpose, then add optional behaviors, recovery semantics, and return value. No filler or 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?

For a tool with 4 parameters, full schema coverage, and an output schema, the description covers the operation, optional modifications, recovery side effect, and return value. 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 description coverage is 100%, so the parameters are already fully documented. The description mentions mode and budget but only echoes the schema; it doesn't add new semantic meaning to any parameter.

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

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

The description names a specific verb and resource ('Resume a paused, halted or interrupted session from its handoff'), which clearly distinguishes it from start_session, pause_session, and stop_session. It also states the optional mode/budget actions, so an agent can tell exactly what the tool is for.

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

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

It gives clear usage context: use when a session is paused, halted, or interrupted, and optionally when you want to switch mode or add budget. It doesn't explicitly name start_session as the alternative for new sessions or list when-not conditions, so it stops 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 provide no hints (all false), so the description carries the burden. It discloses that it returns a sessionId handle and a repository snapshot, and clarifies the budgetMinutes semantics. However, it doesn't explicitly state whether starting a session modifies the repository, whether it can overwrite an existing session, or whether the session starts executing immediately. No contradiction with annotations, but more detail on side effects would be helpful.

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 with the purpose. Each sentence contributes: purpose, mode definitions, and return value/next steps. It's efficient but somewhat dense, mixing mode semantics with workflow hints, so it's not a 5.

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

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

Given the tool's seven parameters, complete schema descriptions, and existing output schema, the description provides enough context for correct invocation. It specifies the required modes, budget requirement, return value, and next steps. It doesn't cover edge cases like session conflicts or failure modes, but these are partially addressed by the schema and output schema. A slightly deeper explanation of the session lifecycle would push this to a 5.

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 adds minor value by clarifying that budgetMinutes is the total wall-clock autonomy 'for the whole session, not per task,' which slightly disambiguates the schema's wording. It does not otherwise go beyond the schema's parameter descriptions.

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 tool starts a work session for a project goal, with a specific verb and resource. It distinguishes itself from sibling session-management tools (pause, resume, stop) by being the entry point, but it doesn't explicitly name resume_session as the alternative for continuing an existing session, so it falls short of a 5.

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

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

The description gives clear guidance on selecting between 'outside' and 'desk' modes, including the budgetMinutes requirement for outside mode. It also suggests next steps, but it doesn't explicitly state when to use this tool versus resume_session or other session tools, nor does it mention any preconditions like having no active session.

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 mark destructiveHint=true, and the description goes well beyond that by detailing exactly what happens: in-flight units are released with checkpoints, the session is classified as resumable/waiting_for_human/blocked/completed, and markFailed:true permanently fails the session. It also notes the final report return value, giving a clear side-effect model with no contradiction.

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

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

The description is three tight sentences, front-loaded with the core action and followed by side effects and the markFailed flag. No filler or redundancy is present.

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

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

For a destructive, non-idempotent tool with a required reason parameter, the description omits what 'reason' should contain and what 'notes' are for. While the output schema may describe the final report, invocation-critical parameter semantics are incomplete.

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 most parameters are already documented. The description repeats markFailed's behavior but does not compensate for the required 'reason' parameter or optional 'notes', neither of which have schema descriptions or explanatory text here.

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 action, 'End the current run', and explains the consequences: in-flight units are released with checkpoints, the session is classified into one of four states, and markFailed:true ends it permanently. This clearly differentiates stop_session from sibling tools like pause_session and resume_session.

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

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

The description implies this tool is for ending a run versus pausing it, and explains that markFailed:true makes the end permanent. However, it never explicitly names the alternative tools (pause_session or resume_session) or states when not to use stop_session, relying on inference.

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

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

With annotations carrying only default/negative hints, the description carries the transparency burden. It discloses atomic rejection on invalid/cyclic ids, explains that later-added units require a rationale, and warns against budget padding. It does not detail side effects of cancel on dependents, but the key behavioral traits are surfaced.

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 with no redundancy; the main operations are front-loaded, constraints follow logically, and the final sentence is a crisp boundary. Every sentence adds 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 the tool's multi-operation complexity and the presence of an output schema, the description covers the essential usage context, validation behavior, and budget expectations. It omits minor details like dependency-cancellation semantics but is sufficient for correct invocation.

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

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

Schema coverage is high (80%), so the baseline is 3. The description adds beyond the schema by explaining upsert semantics, the cancel/reopen actions, and the initial-plan condition that determines when rationale is required, giving inter-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?

The description opens with a specific verb-resource pairing ('Add or update units... cancel or reopen... record project context') that makes the tool's function unmistakable. It also names the distinguishing context ('The first call submits the initial plan'), separating it from read-only siblings like get_work_graph and execution tools like next_work.

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

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

It gives clear context on when to use the tool: the first call initializes the plan, and later calls add/update with rationale requirements. It includes a when-not ('Never add work only to use remaining budget'), though it does not explicitly name sibling alternatives.

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