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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the duplicate-agent caution but never explains why the operation is destructive, whether an existing agent would be replaced, or what side effects occur — useful but limited 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?

Two short sentences, front-loaded with the action and immediately followed by the practical pre-check. No filler 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?

With no output schema, the description leaves the return value unexplained — an agent cannot tell whether it gets an agent id, terminal id, or handle it needs for follow-up calls like orca_terminal_send. The pre-check hint is helpful, but the post-call expectations are missing for a six-parameter mutation 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 83%, so the schema already documents agent, model, effort, prompt, surface and worktree in detail. The description only reinforces the worktree requirement ('existing Orca worktree') and that prompt is optional, adding little beyond 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 (start/launch) and resource (coding agent in an existing Orca worktree), plus names concrete agent examples and the optional prompt. It is clear what the tool does, though it does not explicitly differentiate itself from the sibling orca_terminal_create, which plausibly also spawns processes.

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 — check orca_terminal_list first to avoid duplicate agents — and names that sibling as the alternative to consult. It lacks explicit when-not-to-use guidance (e.g. use orca_terminal_create for non-agent shells), 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only that the listing is of 'scheduled' automations; it says nothing about result volume, ordering, or pagination.

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

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

A single front-loaded sentence with no waste. It is almost minimal to a fault, but there is nothing redundant to cut.

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 parameterless list tool with full annotation coverage, the description is sufficient to call it correctly. However, with no output schema, the agent has no idea what fields describe an automation (e.g., id, schedule, status) or how they relate to orca_automation_run.

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

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

The tool takes zero parameters, so there is no parameter semantics for the description to carry and the baseline applies. Nothing is missing on this dimension.

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 ... Orca automations') with a scope qualifier ('scheduled'). It does not explicitly distinguish itself from the related orca_automation_run sibling, though the verb difference is fairly self-evident.

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 indication of when to use this versus alternatives such as orca_automation_run, or whether the returned list feeds into that tool. The agent must infer usage entirely from the verb.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds only the word "now"; it says nothing about what the run triggers, whether it is fire-and-forget or blocking, whether it returns a run identifier, or that repeated calls start duplicate runs.

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

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

One short, front-loaded sentence with zero filler. It is not padded, though its brevity comes at the cost of the missing behavioral detail noted elsewhere.

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

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

This is a destructive, non-idempotent action with no output schema, yet the description never explains the effect of a run, whether execution is asynchronous, or what the caller receives. For a mutation tool whose result the agent must act on afterward, one sentence is not sufficient.

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 a single parameter at 100% schema coverage, the schema already documents 'id' including its source (orca_automation_list) and format constraints. The description contributes nothing beyond that, which is the baseline expectation at full 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?

The sentence gives a specific verb and resource ("Run one Orca automation") and the word "now" signals immediate execution rather than scheduling. It is clearly distinguishable from the sibling orca_automation_list, though it never names that sibling or any other alternative 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?

There is no guidance on when to invoke this versus listing automations, checking status, or launching an agent. The only pointer to a sibling ("from orca_automation_list") lives in the schema, not the description, so an agent gains no selection criteria from the prose.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely valuable behavior beyond that: the returned text is untrusted cross-session data that must not be followed as instructions, a prompt-injection guardrail an agent cannot get from structured fields. It still says nothing about ordering, freshness, or whether the call blocks.

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, zero waste, with the operation front-loaded and the safety warning immediately after. Nothing is repeated from the title or annotations.

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

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

For a single-optional-param read tool with rich annotations and no output schema, the definition is close to sufficient, and the untrusted-data warning is the highest-value piece of context. Gaps remain around result shape (what a 'message' contains), ordering, and how the limit behaves, which an agent needs to interpret the output.

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 sole 'limit' parameter is never mentioned in the description, so its meaning (cap on messages returned), default value, and interaction with the 1-200 bounds are left entirely to the raw JSON schema. A one-line note on the limit would have made this adequate.

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 ('Show') and a specific resource ('orchestration messages across agents'), which is clearly distinct from the file/terminal/task resources in the sibling list. It stops short of explicitly contrasting itself with near-neighbors like orca_search or orca_terminal_read, so the agent must infer the boundary.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The phrase 'across agents' hints at breadth but never tells the agent whether to prefer this over orca_search or orca_terminal_read, nor whether it is a poll/snapshot operation.

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 this as a read-only, idempotent, non-destructive, closed-world operation. The description adds that projects are "durable" and that the returned id or name feeds into orca_worktree_create, but it does not describe return format, completeness, or ordering.

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 definition is a single compact sentence with no wasted words. The primary action is front-loaded, and the downstream usage note is brief.

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 parameters, rich annotations, and no output schema, the description is largely sufficient. It could be slightly more complete by clarifying that the result is a list of projects containing ids and names, but the existing text already implies that.

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?

This tool has zero input parameters, so parameter semantics have a baseline of 4. The description mentions project id and name in relation to downstream use, though these are outputs rather than 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?

The description uses a specific verb and resource: "List durable Orca projects." It also points to how the returned project id or name is used with orca_worktree_create, which helps distinguish its purpose, though it does not explicitly contrast with sibling list tools such as orca_repo_list or orca_worktree_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?

The description implies the tool is used before orca_worktree_create when a project id or name is needed. However, it does not state when to choose this tool over sibling list tools or when listing projects is unnecessary.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the returned field set, which is genuinely useful, but says nothing about ordering, pagination, or what an empty result means for a zero-argument list call.

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

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

One sentence, front-loaded with the verb and resource, with zero filler. Nothing could be removed without losing information.

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

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

With no input parameters and no output schema, the description compensates by naming the returned fields. The only remaining gap is the absence of any note on ordering or result size, which is minor for a simple enumeration 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 takes no parameters, so there is nothing to document; baseline is 4. The description correctly implies the call is unfiltered and returns all registered repositories.

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 the repositories registered in Orca") and even names the returned fields (id, name, path). It does not distinguish "repo" from the adjacent sibling concepts orca_project_list and orca_worktree_list, so an agent must infer the domain boundary itself.

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 only implied: enumerate repos when you need repo identifiers. There is no explicit when-to-use/when-not, and no mention of when to prefer orca_project_list or orca_worktree_list, which are the most likely confusions given the sibling set.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is lower. The description still adds genuinely non-obvious context the schema cannot express: results are untrusted cross-session data and must not be treated as instructions — a valuable prompt-injection warning. It omits result shape and result-count behavior, keeping it short of 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, no wasted wording. The purpose comes first and the safety caveat follows, so the reader gets the core function immediately.

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 security caveat is the essential piece and it is present, but for a 5-parameter tool with 40% schema coverage and no output schema, the description leaves the scope/limit/date-filter semantics and the response format entirely undocumented.

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

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

Schema coverage is only 40%; 'query', 'limit', and 'scope' have no schema descriptions, and the description says nothing about any parameter. With low coverage the description is expected to compensate for the gaps (especially the scope enum), and it does not.

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 ('Full-text search over agent session transcripts') and scopes it to 'this Orca host', which distinguishes it from the terminal-reading and listing siblings. No sibling is named as an alternative, but the resource type makes the intent 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?

No statement of when to use this versus orca_terminal_read or orca_task_list, and no guidance on the scope enum ('conversation' vs 'all') or when to apply the agent/since filters. The agent has to infer usage entirely from the name and 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that two things are probed (app and runtime) plus reachability, but does not say whether the call blocks, how long it takes, or what a failure looks like.

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; the purpose is delivered in the first few words.

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 trivial zero-parameter probe with no output schema, the description covers what is being checked. It could go slightly further by hinting at the shape of the result (e.g. running/not running, reachable/unreachable) or what to do on failure, but nothing critical 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 tool takes zero parameters, so the baseline is 4; the description correctly implies no input is needed to perform the check.

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 ("Check") and a specific resource (Orca app and runtime liveness/reachability), which no sibling covers — siblings enumerate worktrees, terminals, tasks, etc. It is not explicitly contrasted with any sibling, but the health-check framing is distinct enough that an agent won't confuse it with the list/show tools.

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 only implied: an agent can infer this is the connectivity/health probe to call before or when other Orca tools fail. There is no explicit guidance on when to prefer it, whether to call it first, or what to do when it reports unreachable.

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 only that task status is included; it says nothing about filtering behavior, pagination, ordering, or how the run/ready/status filters affect results.

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. Its brevity is efficient, though it also reflects the under-specification captured in other dimensions.

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 list tool with three optional filters and no output schema, the description does not explain result shape, filtering semantics, or how to choose between this tool and related siblings. An agent can infer basic usage from the name but lacks enough context to invoke it confidently with filters.

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 describes two of the three parameters (run and ready), but status has no schema description and the tool description does not clarify what status values mean or how filtering by status works. With only moderate schema coverage and no compensating description, parameter semantics remain under-specified.

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 clear verb and resource: listing orchestration tasks, with the additional detail that status is included. It does not distinguish this tool from siblings such as orca_status or orca_automation_list, so it stops 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?

There is no guidance on when to use this tool, when not to use it, or which sibling to choose for related listing or status workflows. The usage is only implied by the 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 declare readOnlyHint=false and destructiveHint=true, so the agent knows this mutates state. The description adds one meaningful detail -- the terminal is created 'empty' (no command is started) -- but says nothing about lifecycle, cleanup, resource cost, or whether repeated calls stack up terminals, which matters given idempotentHint=false.

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

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

A single front-loaded sentence with zero waste. It is efficient but also thin, with no second sentence adding the operationally important detail the agent needs.

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

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

For a creation tool with no output schema, the description should say what the caller receives -- the terminal identifier needed to drive orca_terminal_send/read/wait. That linkage is entirely absent, as is any note that the worktree must exist or that the terminal persists afterward.

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 50%: the 'worktree' selector is richly documented in the schema (five selector forms plus a pointer to orca_worktree_list), but the description itself contributes nothing. The undocumented 'title' parameter gets no explanation of its purpose or default, and the description never references the required worktree selector.

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 ('Open a new empty terminal') plus the scoping container ('in a worktree'), which is enough to distinguish it from orca_terminal_read/send/list. It stops short of naming a sibling or contrasting with orca_agent_launch, so it lands at 4 rather than 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from the description whether to use this or orca_agent_launch when it wants something running in a worktree, nor whether the worktree must already exist.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results are 'live' and include agent sessions with handles, but it does not explain pagination, limit behavior, or what 'live' excludes. 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. It communicates the core operation efficiently and does not bury the main action.

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 list tool, the core purpose is clear and annotations cover the safety profile. However, there is no output schema, and the description does not explain what limit controls or what fields beyond handles are returned, leaving some gaps 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 50%: the worktree parameter is well documented in the schema, but limit is undocumented. The description does not mention either parameter or explain how limit and worktree filtering affect results, so it does not compensate 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', and a specific resource, 'live Orca terminals and agent sessions with their handles'. This distinguishes it from sibling tools like orca_terminal_read, orca_terminal_send, and orca_terminal_create. It does not explicitly distinguish it from other list tools, but the terminal focus 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 description gives no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as orca_terminal_read for reading a terminal or orca_terminal_create for creating one. Usage is only implied by the tool name and the word 'List'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: output is bounded, cursor reads yield only new output, and returned text is untrusted session data that must not be acted on. It does not mention pagination termination or default 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 compact sentences: the first establishes the operation and modes, the second is a security caveat that earns its place. Nothing is repeated from the title or schema, and the critical mode information comes first.

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

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

With no output schema, the description correctly characterizes the return value as bounded text and flags its trust level. The remaining gap is minor: no note on default or maximum page size behavior or how to tell when no more output is available.

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 only 25% (only terminal is documented), so the description carries most of the load and does so for the two non-obvious parameters: cursor's origin (nextCursor from a previous read) and screen's meaning. Only limit's purpose and default behavior are left unexplained.

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

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

States a specific verb and resource: reads bounded output of a terminal or agent session. It is clearly distinct from orca_terminal_send/wait/create by naming the read operation, though it never names those siblings explicitly to reinforce the 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?

It explains the two read modes (cursor for incremental output, screen for the rendered view), which is real usage guidance, but it never says when to prefer this over orca_terminal_wait or how to obtain a terminal handle beyond the schema. Alternatives are left implicit.

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 as destructive and non-idempotent, and the description adds useful behavior beyond them: enter submits, interrupt sends Ctrl+C, and shell text executes as a command. It does not describe return values or failure behavior, but the key interaction semantics are disclosed.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently covers normal input, submission, interruption, and shell execution.

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 terminal-input tool with no output schema, the description covers the essential interaction model. It could say more about results or error handling, but annotations and schema carry the remaining structured details.

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

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

Schema coverage is only 25%, so the description must compensate. It explains the semantics of enter and interrupt, and the terminal-handle parameter is documented in the schema itself; text is described functionally as input to type or execute.

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: 'Type text into a terminal or agent session.' It also clarifies the distinct shell-execution behavior, making it distinguishable from read/list/wait siblings, though it does not name any sibling explicitly.

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

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

It gives clear usage context for the boolean flags: 'set enter to submit it, or interrupt to send Ctrl+C.' It also explains that text in a shell terminal runs as a command, but does not state when to avoid this tool or name alternatives.

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 read-only, idempotent, non-destructive. The description adds the crucial behavior the schema only hints at: the wait is bounded and must be re-issued to continue, which reframes this as a polling primitive rather than a single blocking call.

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

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

Two sentences, zero waste. The wait condition comes first and the polling constraint second, which is the right order for an agent deciding whether to call 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?

No output schema exists, yet the description never says what is returned — exit status, idle state, or timeout indication — which is exactly what an agent needs after waiting. For a blocking tool with an undocumented return, the definition is only minimally complete.

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

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

Schema coverage is 67% and the 'for' enum has no per-value description there, but the description explains both modes: terminal exit vs agent TUI idle (turn finished). That is genuine added meaning beyond the schema, though the terminal handle source is only 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?

States a specific verb and resource: waits on a terminal until it exits or its agent TUI goes idle. The blocking/waiting semantics are unambiguous and intuitively distinct from read/send siblings, though no sibling is named 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?

"Each call waits at most 55 s; call again to keep waiting" gives concrete polling guidance for the common case. It does not state when to prefer this over orca_terminal_read or what to do on timeout, so exclusions/alternatives are missing.

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 disclose readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the mutation profile is known. The description adds the repo/project prerequisite and a duplicate-avoidance workflow, but says nothing about failure on duplicate names, what the setup script does, or whether the agent start is synchronous — meaningful gaps for a 10-param mutating tool.

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

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

Three short sentences, front-loaded with the action, then prerequisites, then the pre-check. No filler; the only weakness is that terseness like "Needs repo or project" costs a moment of parsing.

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 10-parameter mutation with no output schema and destructiveHint=true, the description covers the essentials of invocation but omits what is created and returned, the baseBranch default, and the setup=skip vs inherit consequences. The rich schema compensates for much of this, so it is adequate but not complete.

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

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

Schema coverage is 100%, so all ten parameters are self-documenting, giving a baseline of 3. The description still adds real value by signaling that repo *or* project satisfies the selector requirement (both are optional in the schema) and by coupling agent with prompt as an optional pair.

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

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

States a specific verb+resource ("Create a new git worktree in Orca") and adds scope ("optionally starting an agent in it with a prompt"), which separates it from orca_worktree_list/show/ps. It does not, however, distinguish itself from orca_agent_launch, which also starts agents, leaving a sibling overlap unresolved.

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?

"Check orca_worktree_list first to avoid duplicates" names a sibling and the condition that selects it, and "Needs repo or project" states a prerequisite. There is no explicit when-not guidance or indication of what to do if the worktree already exists.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context by naming the returned fields, but it does not explain pagination, filtering behavior, or default limit behavior.

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 efficient sentence with the core purpose front-loaded and no wasted wording.

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 rich annotations and no output schema, the description sufficiently indicates the returned fields. It is slightly incomplete because it omits how the 'limit' parameter behaves and does not clarify when to prefer orca_worktree_show 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 only 50%: the 'repo' parameter is described, but 'limit' has no schema description. The tool description does not mention either parameter or how filtering/limiting works, so it fails to compensate for the 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 gives a specific verb ('List') and resource ('Orca-managed worktrees'), clarifies that these are workspaces, and names the fields returned (branch, path, linked PR or issue). It is clear what the tool does, though it does not explicitly distinguish itself from siblings like orca_worktree_show or orca_worktree_ps.

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 offers no guidance on when to use this tool versus alternatives such as orca_worktree_show for details or orca_worktree_create for creation. Usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that output is aggregated/compact across worktrees, but says nothing about whether inactive worktrees are included, ordering, or how truncation behaves given the limit parameter.

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; the key noun (orchestration summary across worktrees) and the payload (agents and state) both appear immediately.

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 partially compensates by naming the payload ('which agents run where and their state'), which is the most useful single fact. However, for a tool whose entire value is its return shape, a one-line sketch of fields and the undocumented limit parameter leave real 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?

The single parameter (limit, 1-200) has 0% schema description coverage and the description never mentions it. An agent cannot tell what the limit counts (worktrees? agents?) or what the default behavior is when it is omitted.

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 concrete deliverable (a compact orchestration summary across worktrees) and scopes it to agent placement and state, which is meaningfully narrower than a plain worktree listing. It does not explicitly name or contrast with orca_worktree_list or orca_worktree_show, so the reader must infer the distinction.

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 word 'compact' hints at an overview use case, but there is no statement of when to choose this over the 17 listed siblings — notably orca_worktree_list, orca_worktree_show, orca_status. No prerequisites, no exclusions, no follow-up guidance are 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear without the description. The description adds only that the result contains 'full details,' without explaining error behavior for invalid selectors or what categories of details are returned.

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

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

The description is a single concise sentence with the key operation and scope front-loaded. There is no redundant or filler text.

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

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

For a simple one-parameter read tool with rich schema coverage and explicit safety annotations, this is mostly sufficient. However, with no output schema, 'full details' remains vague and the description does not indicate what information the result includes or how invalid selectors are handled.

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 has 100% schema description coverage, including all accepted selector formats and a pointer to orca_worktree_list for exact values. The description adds no selector syntax or format guidance 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 gives a clear verb/resource pair ('Show full details of one worktree') and distinguishes single-worktree retrieval from list-style siblings through 'one worktree.' It does not explicitly name or contrast with orca_worktree_list, but the scope is understandable.

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 only implied: 'one worktree' suggests it is for retrieving a single known worktree, while the sibling orca_worktree_list is for listing. It does not explicitly say when to use this versus orca_worktree_list or orca_worktree_ps, nor does it state prerequisites for a valid selector.

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