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

The description discloses useful behavioral traits beyond annotations: that cancellation is asynchronous ('request cancellation') and that it may still be 'draining' requiring subsequent waiting. However, it does not fully explain the consequences of cancellation (e.g., whether it is reversible, what resources are affected), and it does not contradict the annotations (destructiveHint=true aligns with the cancellation's potential to terminate resources).

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 composed of two concise sentences that front-load the purpose and then provide actionable guidance on next steps. Every sentence contributes to the agent's understanding of both the action and the follow-up needed. No waste or 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?

The description adequately covers the main action and the asynchronous nature, but it lacks details about the returned status format (no output schema) and does not tell the agent what conditions warrant cancellation or how to handle errors. For a tool with destructive implications and no output schema, more context (e.g., typical status values, failure handling) would be beneficial.

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 has one parameter, 'run_id', with no description in the schema (0% coverage). The description references the run but does not elaborate on the format of 'run_id' or how to obtain it (e.g., from 'get_run' or 'start_run'). Since the description does not add significant semantic detail beyond the schema, a baseline of 3 is appropriate, given the simplicity of the 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 states a specific verb ('cancel') and a resource ('a specific run'), which clearly distinguishes it from sibling tools like 'get_run' or 'wait_run'. It also indicates a non-blocking behavior ('request cancellation'), though it could more explicitly contrast with synchronous cancellation or mention that it is for ongoing runs.

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 hint of the workflow ('Inspect the returned status, and wait again if cancellation is still draining') but does not state when to use this tool versus alternatives like 'wait_run' or 'get_run'. It lacks explicit exclusions (e.g., not for completed runs) and does not mention when cancellation is appropriate or prerequisites (e.g., run must be running).

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 read-only, destructive, and idempotent basics. The description adds valuable nuance: idempotency is scoped to the same daemon lifetime within 24 hours, and restart/expiry invalidates the guarantee. This goes beyond the annotations, though auth and failure modes are not discussed.

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

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

Two tight sentences: the first states the core purpose, the second front-loads the important idempotency caveat. No filler; 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?

It covers the core action and the most important idempotency caveat, but with no output schema it does not tell the agent what to expect on success, such as a project ID or whether creation is asynchronous. The meanings of name, description, and agent_context are also left to inference.

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

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

Schema description coverage is only 25% (idempotency_key), and the description elaborates only on that parameter's retry semantics. The other three parameters (name, description, agent_context) receive no semantic explanation in either the schema or the description, so the description does not compensate for the coverage gap.

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

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

States a specific verb ('Create') and resource ('project'), and adds the visibility outcome ('visible in Open Science'). No sibling tool creates a project, so the boundary is clear.

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 opening sentence establishes when to use the tool: to create a new project. The retry caveat also tells the agent to inspect existing projects after restart or expiry rather than blindly retrying, which is useful context, though no specific sibling tool is named.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description says 'Approve or give feedback in Open Science UI,' which implies the tool mutates state. That directly contradicts the annotations. The description also fails to clarify return shape or behavior for missing sessions.

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 first sentence is concise and front-loaded. The second sentence does not earn its place and actively confuses the read-only nature of the tool, making the overall structure only passable.

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

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

With no output schema, the description should explain what the agent will get back. It mentions 'plan and approval state' but omits approval state details, session_id mapping, and error behavior, while adding contradictory UI guidance. This is incomplete for reliable tool selection and 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?

The schema has 0% description coverage for the only parameter, session_id, and the tool description never explains how session_id selects the plan or approval state. The parameter name is suggestive, but the description does not compensate for the missing schema documentation.

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

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

The first sentence names a specific read operation on a clear resource ('current plan and approval state'), so the core purpose is clear. However, the second sentence introduces approve/feedback actions that are not read operations, and the description does not differentiate it from siblings like get_status 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 guidance is provided about when to use get_plan versus alternative read tools such as get_status or get_session. The mention of approving and giving feedback suggests user actions in a UI rather than a usage condition or exclusion.

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

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

Annotations already label this as safe/read-only/idempotent/non-destructive, so the bar is lower. The description adds a behavior not fully encoded in annotations: the uncertainty that a terminal status is not necessarily 'done' and attention data is part of the state. This enriches the agent's model beyond the 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?

Two sentences with no redundancy: the first states the main function, the second provides a crucial caveat. The most important instruction (inspect attention) is front-loaded as a second sentence right after the purpose, and every word earns its place.

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

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

For a single-parameter read-only tool with no output schema and full safety annotations, the description covers the key fields and the common failure to inspect attention. It does not explain the return structure in detail, but that is acceptable given a simple input and no explicit expectation of a structured output schema. The missing piece is a note on how to obtain the run_id, but that is often inferable.

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

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

Schema coverage is 0%, so the description is expected to compensate for the parameter semantics. It modestly does so by making clear that run_id identifies a run, and the run's status/output/attention/artifacts are retrieved. It stops short of noting where run_id comes from (e.g., start_run) or what format it takes, so it only partially compensates for the lack of 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 states a specific verb ('Get') and a specific resource ('run'), and enumerates the returned scope: status, current output, attention, and artifacts. It does not explicitly distinguish itself from the sibling get_status or list_artifacts, but the combination of these fields makes the purpose clear and 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 second sentence gives actionable guidance: a terminal status may still require attention, so the agent should inspect the attention field before declaring completion. This addresses a subtle trap and instructs when and how to interpret the response, though it does not name alternatives such as get_status or wait_run.

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 read-only, idempotent, and non-destructive behavior. The description adds useful context by clarifying that the response is a summary plus waiting status, not full history. It does not disclose behavior for missing sessions, error conditions, or response formatting, but the annotation safety profile lowers the burden.

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 with no filler. The main action and return scope are front-loaded, and the clarifying constraint about message history is placed immediately after. Every word earns its place.

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

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

For a one-parameter read tool with strong annotations, the description is mostly complete: it states what is returned and what is not returned. It falls slightly short by not describing the shape of the summary/status response or how to source session_id, but these are minor gaps given the tool's 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 0%, and the description does not compensate by explaining session_id: its format, where to obtain it, or how it relates to list_sessions or get_run. The parameter name is self-explanatory, but the description adds no meaningful semantics beyond the schema's bare field definition.

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

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

The description opens with a specific verb and resource: 'Read a session summary and waiting status.' It also draws a clear boundary with 'This is not complete message history,' which helps distinguish this tool from broader history/retrieval tools. Even without naming a sibling explicitly, the purpose is specific 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 implies when to use the tool: when a summary or waiting status is needed, and not when full message history is required. However, it provides no explicit guidance about alternatives like get_status, get_run, or list_sessions, and no exclusions beyond 'not complete message history.'

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, idempotentHint, and destructiveHint=false, so the description's statement that it does not start or configure is consistent and adds minimal new context. Without annotations, it would need to say it's non-mutating and safe to call repeatedly, which the description partially does but not explicitly for a no-parameter tool. The description adds little beyond annotations; it could clarify what 'readiness' means or what the response contains.

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, short sentence with no filler. It front-loads the primary action ('Inspect') and the object, then adds a clarifying exclusion. Every word earns its place; 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 has no parameters and no output schema, the description is relatively complete for a status check. However, it doesn't specify the response format (e.g., what fields are returned), which could be important for an agent to interpret the status. With no output schema, the description could reasonably mention the type of information returned. This is a minor gap but not critical for a no-parameter inspection 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?

The tool has zero parameters, and schema coverage is 100% (vacuously, since no properties are defined). The description doesn't need to explain parameters, so with no parameters, a baseline of 4 is appropriate. The description adds context about what the tool checks, which is sufficient.

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 'inspects' a specific resource ('local service and model/runtime readiness') with a specific verb. It distinguishes from configuration by adding 'Does not start or configure the app,' which helps differentiate it from sibling tools like start_run or create_project, though it doesn't explicitly name them.

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

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

The description implies the tool is for checking readiness before starting or configuring, but it doesn't explicitly state when to use it versus alternatives. The phrase 'Does not start or configure' hints at exclusions, but there's no direct mention of other tools or conditions, leaving some inference to the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping detail that only 'finalized' artifacts are listed, but it does not disclose ordering, pagination, or failure behavior. There is 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 front-loaded sentence with no filler or redundancy. Every word contributes to the core purpose, making it very easy to scan and quickly understand the tool's role.

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 read-only listing tool, the description is nearly sufficient, but the absence of an output schema raises the bar. It would be more complete if it clarified whether the response contains artifact content, metadata, or only URIs, and how that relates to read_artifact.

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

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

Schema description coverage is 0%, and the description never mentions session_id. The parameter name is somewhat self-explanatory, and the phrase 'session artifacts' implies that session_id identifies the relevant session, but the description does not clarify the expected provenance or format of session_id beyond the schema's length constraints.

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 ('List') and names a concrete resource ('finalized session artifacts and MCP resource URIs'). It is distinguishable from siblings like read_artifact and list_sessions, though the phrase 'MCP resource URIs' is jargon-heavy and leaves some ambiguity about exactly what is returned.

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

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

There is no guidance about when to use this tool versus alternatives such as read_artifact, get_session, or list_sessions. The appropriate trigger condition—for example, needing artifact metadata or URIs after a run finalizes—is left entirely 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and the description consistently aligns with them—no contradiction. It adds only the return-value focus ('stable IDs'), which is a small behavioral contribution beyond the annotations, but it says nothing about pagination, ordering, or output size.

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 front-loaded sentence with no filler or redundancy. Every word earns its place: verb, scope, resource, and an output-relevant detail. The example is exactly as concise as a flat list tool needs.

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

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

For a zero-parameter, read-only list tool with stable output hints in the description, little more is required. The description covers what the tool returns ('stable IDs') despite the absence of an output schema, which helps the agent interpret downstream steps like get_run and read_artifact. Minor missing context on filtering or scoping is acceptable given the tool's 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?

The tool has zero parameters and 100% schema description coverage, so there is nothing for the description to clarify. Per calibration, 0 params earns a baseline of 4, and the description correctly avoids inventing fake parameter guidance.

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 ('List'), resource ('Open Science projects'), and output content ('stable IDs'). It clearly distinguishes from siblings like list_sessions and list_artifacts by naming the project resource, and from create_project by the verb. An agent can reliably route to this tool without opening the schema.

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

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

The description gives no guidance on when to use this tool versus alternatives. With siblings like list_sessions, list_artifacts, and create_project, there is no explicit when-to-use, when-not-to-use, or alternative routing. The name 'list_projects' implies against the siblings, but nothing is 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a useful behavioral nuance by specifying 'summaries', implying the tool returns condensed data rather than full session details. However, it does not disclose pagination, limits, or filtering behavior beyond the project scoping. With annotations covering the major traits, a 3 is appropriate.

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, front-loaded with the action ('List session summaries') and the optional modifier. Every word carries meaning, with no filler or repetition. 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?

For a simple read-only list tool with one optional parameter and no output schema, the description is largely complete. It states the purpose, the optional scoping, and implies summary-level output. It does not mention pagination or result ordering, but these are minor given the tool's simplicity and lack of an output schema to elaborate on.

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

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

The schema provides no description for project_id (0% coverage), but the description explicitly explains it as an optional scoping filter by project. This adds meaningful semantic context beyond the bare string type, though it does not elaborate on the exact semantics of 'project' or whether multiple projects can be specified. Still, it compensates well for the schema gap.

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

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

The description states a specific verb ('List'), a clear resource ('session summaries'), and an optional scoping condition ('scoped to a project ID'). This distinguishes it from sibling tools like get_session (singular retrieval) and list_projects (different entity type), leaving no ambiguity about its function.

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 clearly conveys when to use the tool (to list session summaries) but does not explicitly mention when not to use it or suggest alternatives. It provides clear context but lacks explicit exclusions or routing to sibling tools, so it earns a 4 rather than a 5.

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

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

The description goes well beyond annotations by disclosing the 100 MiB download limit, the parent-directory requirement, the never-overwrite guarantee, and checksum verification when metadata provides it. This is especially valuable given readOnlyHint=false, since it clarifies the download path writes a file.

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

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

Three compact sentences, with the primary purpose front-loaded and download behavior following. Every sentence carries new, non-redundant information.

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

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

The main modes, constraints, and safety behavior are covered despite no output schema. It stops just short of full completeness by not specifying what an 'inline image' vs 'resource link' response looks like or the exact failure behavior when output_path's parent does not exist.

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

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

With 0% schema description coverage, the description compensates by explaining byte-window reads and adding meaningful detail to output_path (absolute path, parent must exist, no overwrite). session_id and artifact_id are self-explanatory identifiers, and offset/max_bytes constraints are already in 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 enumerates exactly what the tool does: read a UTF-8 text byte window, inline a small image, or return a resource link. This is a specific verb-resource pairing and the three modes clearly distinguish it from session/run/artifact management siblings.

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

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

It gives an explicit conditional for full-file download: supply an absolute output_path whose parent exists. It doesn't name alternative tools, but no sibling offers the same read functionality, so the mode-based guidance is sufficient.

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 (readOnly=false, idempotentHint=true), the description discloses model cost, approval persistence in the Open Science UI, and the narrow idempotency guarantee tied to daemon lifetime and a 24-hour window. This materially changes how an agent should reason about retries and side effects, 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 dense sentences carry high-value information: cost, session continuity, cwd constraint, approval behavior, return value, and idempotency limits. There is no filler or repetition of schema content.

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 has six parameters, no output schema, and meaningful side effects, the description covers the critical operational facts: cost, approvals, run ID return, cwd constraint, and retry protection limits. It is slightly weak on how to discover or supply session_id and what turn_intent='plan-first' implies, but it is largely 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 description coverage is only 17%, so the description must compensate. It adds meaning for cwd (must match the session directory), session_id (continue an existing session), and idempotency_key (retry limitations), but it does not clarify project_id, prompt, or turn_intent, leaving some parameter semantics to inference.

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

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

The description names two distinct actions: submitting research and continuing an existing session, with a clear resource (a run). It implicitly distinguishes itself from read-only siblings like get_run, wait_run, and list_sessions by focusing on submission/continuation, so an agent can tell when to select it.

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

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

It gives concrete usage context: start a new submission or continue a session, and requires cwd to match the session directory on follow-ups. It also directs the agent to poll/wait on the returned run ID, suggesting the appropriate follow-up tools, though it does not explicitly name alternatives 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?

The description adds real behavioral context beyond the annotations: it can return early on completion or user/permission/plan attention, and a timeout does not mean cancellation. This is valuable and consistent with the read-only, idempotent annotation given. It earns high marks, though it leaves vague what exactly the caller should do when 'attention' causes the early return.

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 crisp sentences, each carrying essential information: the wait duration, the early-return conditions, and the cancellation distinction. There is no filler or repetition, and the most important facts are 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?

The description gives enough to invoke the tool correctly in most cases, but there is no output schema and the description does not explain what the tool returns or how an agent distinguishes a timeout from a completed run or an attention state. For a tool whose only observable result is the return value, this is a meaningful gap.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It adds useful semantics for timeout via 'timeout means research continues,' but it does not mention run_id at all and does not explain how timeout_ms maps to the 30-second maximum, which is already in the schema. Because only one parameter is partially addressed, the description does not carry the parameter-documentation burden.

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 identifies the tool as a blocking wait operation on a run ('Wait up to 30 seconds') and contrasts it with cancellation in a way that distinguishes it from siblings like get_run and cancel_run. The behavior of returning early on completion or attention is stated explicitly, so an agent does not have to infer the core purpose.

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

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

The description gives concrete guidance about timeout behavior and explicitly names cancel_run as the only way to actually cancel the run. It does not explicitly tell the agent when to use wait_run versus get_status or get_run for non-blocking checks, so it misses full alternative routing, but enough context is present to avoid misusing the tool.

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