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

With no annotations provided, the description carries the full behavioral burden, and it handles this well: it discloses what the tool does (ingests into ephemeral search index), what it returns (compact versioned JSON summary), what it preserves (named metrics in structured_metrics), and an important nuance about limit semantics not validating filesystem intent. It doesn't describe error behavior or what happens on oversized files, but the provided behaviors 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?

Two focused paragraphs with the primary purpose front-loaded in the first sentence. The second paragraph earns its place by conveying safety-critical file-handling guidance. No filler or repetition of the schema; every sentence contributes new information, though it could be slightly tightened.

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

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

The tool has 5 parameters, an output schema (which covers the return format), and no annotations. The description adequately covers purpose, return behavior, and file-path validation, but leaves label and content_type semantics unexplained. For a file-ingestion tool with output schema present, it's close but not fully complete—an agent might misuse label or content_type without schema-level descriptions.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly explains max_bytes ('use an explicit bounded max_bytes for large or untrusted files'), file_path (via the validation guidance), and structured_metrics ('preserves optional named metrics'). However, it never addresses label or content_type, leaving two of five parameters undocumented in both schema and description, so compensation is only partial.

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 ('Reads a file or log output from disk and ingests it') with a clear resource, distinguishing itself from siblings like capture_text (which would capture text directly) and execute_and_capture (which captures execution output). It also states the output format ('compact versioned JSON summary') and the optional structured metrics, making the tool's distinct purpose 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 paragraph gives concrete pre-call guidance: resolve symlinks when path identity matters, confirm workspace membership, and use a bounded max_bytes for large/untrusted files. It also clarifies the boundary condition ('Capture limits control output handling; they do not validate filesystem intent'). It provides clear context for safe usage, though it doesn't explicitly name alternatives or state when NOT to use this tool in favor of a sibling.

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

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

No annotations are provided, so the description carries the burden. It explains the return value (compact versioned JSON summary) and that structured_metrics are retained, but it never explicitly states the side effect of ingestion: whether the text is persisted to a capture store, becomes searchable, or has limits/idempotency behavior. Adds context but leaves the core storage behavior implied.

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 with the main purpose front-loaded, followed by usage guidance and return-value note. Slight redundancy between 'return capture metadata' and 'return value is a compact versioned JSON summary,' but the description earns each sentence and remains efficient.

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 4-parameter tool with no annotations and 0% schema coverage, the description covers the primary use case, a key alternative, and the return shape, and an output schema exists. It is incomplete on side effects and two parameters ('label', 'content_type'), which an agent needs to craft correct calls.

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

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

Schema description coverage is 0%, so the description must explain parameter meaning. It clarifies 'content' by referring to already-collected text and hints at 'structured_metrics' as optional named metrics, but 'label' and 'content_type' (including the 'auto' default) are never explained, leaving significant parameter semantics undocumented.

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

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

The opening sentence states a concrete action ('Ingest already-collected text') and the result (return capture metadata), which distinguishes it from the sibling execute_and_capture. It names what input is expected and what the tool is not for (collecting output from command execution).

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

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

Explicitly tells an agent when to use it ('when the caller already has output to index') and when to prefer execute_and_capture for noisy/long commands, with a reason (keeping output bounded before agent context). This routes the agent to the correct sibling without ambiguity.

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

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

With no annotations, the description carries the behavioral disclosure burden and does reveal the main side effect ('Clears') and the underlying goal ('free memory'), as well as the ephemeral nature of the buffer. It stops short of stating irreversibility or the consequences of clearing all, though the ephemeral phrasing softens that gap.

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. Every word adds meaning: the action, the target, the scope, and the purpose.

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 low-complexity tool with one optional parameter, an output schema, and no annotations, the description covers the action, scope, and purpose sufficiently. A minor gap is not explaining how to identify the specific capture, but the parameter schema and title provide enough context.

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

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

Schema coverage is 0%, so the description must compensate. It partially does by indicating that either 'all' or a specific capture can be cleared, which aligns with the default 'all' and the capture_id parameter name, but it does not explicitly explain how to supply a capture_id.

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 ('Clears') and resource ('capture from the ephemeral buffer') and explicitly covers the all-or-specific scope. It does not name a sibling for contrast, but no sibling appears to perform clearing, so the purpose is readily distinguishable.

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 phrase 'to free memory' gives an implicit usage context: use this tool when captures in the ephemeral buffer should be removed. However, it does not state when not to use it or compare it with related tools such as consolidate_captures or get_buffer_stats.

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

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

With no annotations present, the description carries the full burden and does a good job: it discloses that source capture IDs and line numbers are preserved, that sources remain reachable through their original IDs until LRU eviction, and that the operation fails if the consolidated capture cannot be admitted while retaining sources. What it does not clarify is whether the originals are ever removed by a successful consolidation, leaving a small ambiguity about destructiveness.

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

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

Three short sentences, front-loaded with the core action and then the retention and failure behavior. No filler, though the phrasing around admission failure is slightly heavy for the information conveyed.

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

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

An output schema exists, so return values need no explanation, and the retention/failure semantics are covered. However, for a tool with four fully undocumented parameters, the description omits any guidance on capture_ids, max_captures, or max_bytes, which leaves a meaningful gap for correct invocation.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and largely does not. It hints at capture_ids ('from multiple captures') and max_bytes ('bounded', 'If records do not fit'), but never names or explains label, max_captures, or the size constraint semantics, leaving half the parameters undocumented in both places.

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

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

States a specific verb and resource: 'Create one bounded, searchable JSON capture from multiple captures.' That is clearly distinguishable from siblings like capture_text, capture_file, and search_capture. It stops short of naming a sibling or scoping when this is preferred, so it is clear but not maximally differentiated.

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: the agent can infer this is the tool for merging several existing captures rather than creating one. There is no explicit statement of when to prefer it over capture_text/capture_file, nor any exclusions. Implied-but-unstated context warrants a 3.

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

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

With no annotations provided, the description carries the full disclosure burden and succeeds: it warns that an omitted cwd inherits the server process directory, that symlinks/shell expansion can target unexpected paths, that it 'bounds output but does not validate command intent, path identity, or filesystem safety', and that timeouts return exit code 124. This is exemplary safety disclosure for a shell-execution 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?

Purpose is front-loaded and every block earns its place — return contract, routing heuristic, safety warnings, then Args. It is longer than average, but the length is justified for a risky, 7-parameter shell tool; the structured_metrics omission in Args is the only structural blemish.

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 complex tool (7 params, output schema, high-risk shell execution, 17 siblings), the description covers purpose, routing, safety, return contents, and all parameters. An output schema exists so return-value details don't need duplication. The small remaining gaps are the unnamed direct-execution sibling and the unlisted structured_metrics parameter.

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 and largely does: command, cwd (with 'pass an explicit validated path' guidance), label, content_type (with its enum values listed), max_output_bytes, and timeout_seconds (with the 124 exit-code semantic) are all explained. The one gap is structured_metrics, which is only hinted at as 'optional named metrics' in the return summary and never appears in the Args list.

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?

Opens with a specific, multi-verb purpose ('Runs a shell command, captures stdout/stderr, indexes it, and returns a compact versioned JSON summary') tied to a concrete resource and a distinguishing behavior (bounded capture + indexing). The return contract (status, duration, sizes, token counts, truncation, signals) makes it unmistakable against siblings like get_execution_output or capture_text.

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

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

Gives explicit when-to-use conditions ('noisy tests, builds, logs... bounded capture and later search') and an explicit when-not ('Direct command execution is usually faster for a small, targeted inspection'). Also frames it as an advisory heuristic rather than an enforced threshold, which prevents the agent from over-trusting the rule.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It implies a non-mutating read by saying 'Returns' and names the metric categories, but it does not mention side effects, freshness, performance cost, or any caveats. For a zero-parameter diagnostic this is adequate but not comprehensive.

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 with no filler. It leads with the action and then lists the specific metric areas, making efficient use of every word.

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, no-parameter read with an output schema present, the description is mostly sufficient. However, it leaves unresolved how this tool relates to get_runtime_diagnostics or when one should be preferred, creating mild contextual ambiguity for an agent choosing among sibling tools.

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 no parameter semantics to explain. The description adds nothing parameter-specific, but none is needed; this is the appropriate baseline for a parameterless tool.

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

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

The description clearly states a read operation ('Returns') and a specific resource: aggregate capture, accounting, prefetch, and process RSS metrics. It is more specific than the tool name alone, though it does not explicitly differentiate itself from the similarly diagnostic sibling get_runtime_diagnostics.

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 versus alternatives like get_runtime_diagnostics. No context is provided about typical scenarios, prerequisites, or why an agent would prefer this tool over a sibling.

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

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

No annotations are provided, so the description carries the behavior disclosure burden. It does clarify that this is a non-mutating fetch, that lines are 1-indexed, and that the slice is exact. However, it does not mention the default 'latest' capture_id behavior, invalid-range handling, or what happens when the capture does not exist.

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 sentence with no filler. The core action, resource, key constraint (1-indexed), and purpose are all front-loaded in an efficient way.

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 is adequate for a simple read-only slice operation, and the output schema covers return shape, but it lacks explicit routing among siblings and fails to mention capture_id default behavior or error conditions. It is usable but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful meaning for start_line and end_line by stating they define a 1-indexed exact range, but it never explains capture_id or its 'latest' default, leaving one of the three parameters 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?

States a concrete operation ('Fetches... range of lines'), the resource ('from a capture'), and the intended use ('inspect full context around a match'). The verb and scope distinguish it from sibling tools like search_capture, get_capture_summary, and list_captures even without explicitly naming 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 usage after finding a match, so the context is fairly clear, but it does not explicitly state when to use this tool versus search_capture or list_captures, nor does it provide exclusions or alternatives. The guidance is implicit rather than direct.

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

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

With no annotations provided, the description carries the full disclosure burden. It conveys that the call is non-mutating ('Returns'), that output is a 'compact versioned JSON' format, and that the full output is deliberately excluded — useful behavioral context. It does not disclose error behavior for an unknown capture_id or any rate/availability constraints, though these matter less for a simple read.

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 zero filler: the verb-resource purpose is front-loaded, and the parameter guidance plus sibling pointer follow immediately. Every clause carries information.

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

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

An output schema exists, so return values are documented elsewhere and need not be repeated. The main gaps are capture_id, undocumented in both the schema (0% coverage) and the description, and the absence of annotations for safety signals; for a simple two-parameter read tool this is adequate but not thorough.

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

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

Schema description coverage is 0%, so the description must compensate; it does for include_previews ('head and tail samples') but never mentions capture_id, the parameter that selects which capture is summarized. The meaning of the 'latest' default and the behavior for an invalid id are left entirely to inference from sibling tool names.

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

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

The description opens with a specific verb-resource pair — 'Returns a compact versioned JSON summary' — and differentiates the tool from its sibling get_capture_slice by noting that 'full output remains available' there. It falls short of a 5 because it never states what the summary actually contains (which fields or statistics), leaving the agent to infer scope from the output schema.

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

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

It gives concrete selection guidance: enable include_previews 'when head and tail samples are needed' and use get_capture_slice when full output is required. The compact-versus-full contrast makes the decision rule clear, though it stops short of an explicit 'use this when you only need summary statistics' statement.

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

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

With no annotations, the description carries the behavioral disclosure burden. 'Return' clearly signals a read-only operation, and 'durable phase metadata' adds useful context about persistence. However, it does not disclose behaviors such as pagination, error conditions, or the effect of include_output, so transparency is only partially addressed.

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 redundant words. It is concise and scannable, though the term 'durable' is slightly jargon-heavy and could be clearer.

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 is adequate for identifying the tool's purpose but incomplete for confident invocation: it lacks parameter explanations, usage guidance, and behavioral details beyond 'Return'. The presence of an output schema helps, but it does not cover parameter semantics or alternative routing.

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 execution_id or include_output. It omits include_output entirely, so an agent gains little parameter-level meaning beyond the schema's names and types.

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 ('Return') and a specific resource ('durable phase metadata and event history for one execution'). It distinguishes this tool from siblings like get_execution_output and list_executions by emphasizing a single execution's metadata/history rather than output or multiple executions.

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 this tool versus alternatives such as get_execution_output or list_executions. The phrase 'for one execution' hints at scope, but there are no explicit conditions, exclusions, or selection criteria.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the operation returns a single bounded chunk rather than full output, and that phase filtering is available. It does not discuss pagination semantics or encoding, but for a read-only retrieval tool this is meaningful behavioral 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?

A single front-loaded sentence with no filler; it states the action, resource, chunking behavior, and phase option compactly.

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-oriented tool with a rich output schema and a single required parameter, the description plus schema is mostly sufficient to invoke correctly. It could better explain paging/offset semantics, but with defaults and constraints in the schema this is a minor 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. It clarifies phase_name ('one named phase') and the bounded-chunk nature of max_bytes/offset, but it does not define offset semantics or explicitly connect execution_id to the required parameter. The schema's self-explanatory titles and constraints carry much of the remaining weight.

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 action ('Retrieve') on a specific resource ('execution output') and narrows it to a bounded chunk with optional phase scoping. It is clear enough for selection, though it does not explicitly distinguish itself from sibling tools like get_execution or get_capture_slice.

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 phrase 'for all phases or one named phase' gives context about when phase_name matters, but there is no explicit guidance on when to prefer this tool over alternatives or when not to use it. Usage is implied rather than 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?

With no annotations, the description bears the full disclosure burden. It adds useful context by stating the tool is opt-in and avoids exposing captured content, implying a read-only diagnostic operation. However, it does not describe any side effects, permissions, or conditions under which metadata is available.

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

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

The description is a single sentence that is front-loaded with the core action and followed by an important boundary statement. There is no filler, and every phrase 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?

Given the tool has no parameters, an output schema, and a fairly simple diagnostic purpose, the description is mostly complete. It lacks guidance on when or why an agent should invoke it, but the output schema covers return values and the boundary statement clarifies what it does not expose.

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 the schema coverage is 100%, so there is no parameter information missing. The baseline for a no-parameter tool is 4, and the description does not need to add parameter-level detail.

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 returns runtime metadata and explicitly distinguishes it from exposing captured content, which separates it from sibling capture tools. The resource 'runtime metadata' is somewhat vague, but combined with the tool name it 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?

No guidance is provided about when to use this tool instead of siblings. The phrase 'opt-in runtime metadata' hints at a prerequisite condition but does not explain how or when to opt in, and no alternatives are mentioned.

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

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read operation by saying 'Return', but does not state side effects, permission requirements, or semantics of the snapshot token. The phrase 'content-free' hints at output characteristics but not safety or cost.

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, tight sentence that front-loads the core purpose and includes the optional parameter behavior. Nothing is redundant.

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

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

With no annotations and a non-trivial token concept, the description leaves gaps: it does not state whether the call is safe/read-only, how to get a snapshot token, or what 'usage metrics' are aggregated over. The output schema helps, but the token semantics need more coverage.

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

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

There is one parameter ('since') and schema coverage is 0% because the schema only says it can be a string or null. The description adds 'snapshot token' semantics, which is useful, but it does not explain what a snapshot token is, how to obtain one, or how it filters results.

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

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

The description names a specific resource ('usage metrics') and a distinguishing trait ('content-free'), which separates it from sibling tools that operate on captured content. The optional 'since a snapshot token' clarifies the input. Not maximally specific about what 'usage' means, but enough to identify intent.

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 on when to choose this tool over siblings like get_buffer_stats or get_runtime_diagnostics, nor any exclusion criteria. The 'content-free' hint implies not for content, but it is not explicit.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It usefully signals that the buffer is ephemeral and that the result reflects whatever is currently retained, implying a read-only listing. However, it does not mention ordering, empty-buffer behavior, or whether the listing affects buffer state.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds meaning: 'all captures', 'currently retained', and 'ephemeral ring buffer' all contribute to accurate selection and invocation.

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 list operation with an output schema available, the description is complete enough. It tells the agent exactly what the tool returns and the scope of that return, and nothing else is needed to invoke it correctly.

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

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

The tool has zero parameters, and the schema confirms this, so there is no parameter documentation burden. The description focuses on the operation rather than inputs, which is appropriate for a no-argument tool.

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 ('Lists') and a clear resource ('all captures') with an explicit scope ('currently retained in the ephemeral ring buffer'). This distinguishes it from sibling tools like search_capture and get_capture_slice, which imply filtering or partial access.

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

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

The description gives clear context: use this tool when you need the complete set of currently retained captures. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5, but the intent is not left 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does reveal that results are compact partial/completion summaries rather than full execution records, but it does not mention read-only behavior, pagination semantics, ordering, or what 'durable' means in this 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?

The description is a single front-loaded sentence with no filler. It communicates the action, the resource, and the nature of the returned summaries efficiently.

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

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

For a simple paginated list tool with an output schema, the description covers the core behavior sufficiently. It lacks details like ordering or total count, but those are likely already represented in the output schema, and the parameter surface is minimal.

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 adds no meaning for the limit and offset parameters. The parameter names and schema constraints are self-explanatory enough for simple pagination, but the description does not compensate for the lack of schema descriptions as required when coverage is low.

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: 'List durable executions'. It also identifies the result shape as 'compact partial/completion summaries', which clearly distinguishes this listing tool from siblings like get_execution or get_execution_output that imply retrieving a single execution or its full output.

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

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

The description implies this tool is used when a list of executions with summaries is needed, but it does not provide explicit when-to-use guidance or contrast with alternatives such as get_execution, get_execution_output, or list_captures. The usage context is clear but only implied.

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

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

With no annotations provided, the description carries the full burden and does so strongly. It explicitly says the command is never executed, that diagnostics are content-free, and that more advanced shell features cannot be verified. This gives the agent a clear and honest safety profile.

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 concise, front-loaded with the core behavior, and every sentence earns its place. The second sentence adds exactly the necessary detail about what is resolved and what cannot be verified, without bloating.

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 is complete for a preflight diagnostic tool: it states purpose, safety guarantees, scope of resolution, and limitations. Since an output schema exists, it does not need to describe return values. A small gap is that `cwd` is not explicitly tied to the 'working directory' mention, but the overall context is 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?

The input schema has 0% description coverage, so the description must compensate. It clarifies that `command` is the operation to inspect rather than execute, and that working-directory resolution is involved, which indirectly covers `cwd`. However, it never explicitly names or explains the `wd` parameter's meaning or default behavior beyond the schema's `default: null`.

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

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

The description states a specific action and resource: it returns content-free path and executable diagnostics for a command without running it. This clearly distinguishes it from execution-oriented siblings like execute_and_capture by emphasizing safety and static analysis.

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 makes the use context clear: use this when you need path, symlink, git root, or executable-token diagnostics without side effects. It also explicitly lists what cannot be verified here, such as shell expansion, aliases, pipelines, and redirections, signaling when the tool is not suitable. It does not name an alternative, but the boundary is well implied.

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

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

With no annotations, the description carries the full burden. It transparently discloses that completed phases are skipped, that failed/timed-out phases need retry_failed, and that unsafe retries require confirm_unsafe unless the policy permits. It does not mention potential side effects, error cases, or what happens if no incomplete phases exist, but the disclosed behavior is substantial and goes beyond a generic 'resume' statement.

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 sentences, front-loaded with the core action and scoping. It efficiently packs behavioral rules without redundancy. The structure is logical: purpose, phase handling, then retry conditions. No wasted 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?

Given the tool's complexity (multiple phases, retry logic, safety policies) and that an output schema exists (so return format is covered), the description is fairly complete. It covers the key decision points an agent needs: skipping completed phases, requiring retry_failed for failures, and confirm_unsafe for unsafe retries. It does not mention edge cases like no incomplete phases or errors, but the core usage is well specified.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the retry_failed and confirm_unsafe parameters by stating when they must be set (retry_failed for failed/timed-out phases, confirm_unsafe for unsafe retries without the allow-unsafe policy). It does not explain execution_id, but that is self-evident as the identifier. The description adds meaningful semantics beyond the schema's bare parameter definitions.

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 ('Resume') and resource ('an execution'), and precisely defines the scope as 'from its first incomplete phase'. It clearly distinguishes itself from siblings like start_execution by focusing on resuming rather than starting, and from get_execution by being an action rather than a read.

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 provides clear context on when to use it (to resume an execution) and specifies conditions for retries (failed/timed-out phases require retry_failed, unsafe retries require confirm_unsafe unless policy allows). However, it does not explicitly state exclusions or alternatives beyond implying that start_execution is for new executions. The usage context is strong but not fully explicit about when not to use it.

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

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

With no annotations, the description carries the full burden and does so unusually well: it discloses that hybrid may return BM25 results marked 'pending' while an index job continues, that semantic indexing is bounded by per-capture byte and token budgets, and that oversized captures fall back to immediate BM25. It omits permission/auth requirements, but the latency, fallback, and pending-state semantics are exactly the kind of hidden behavior an agent needs.

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

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

Purpose is front-loaded in sentence one, followed by behavioral caveats and then a clean Args list; nothing is wasted in a structural sense. The budget/wait prose is somewhat dense and partially repetitive (budget behavior is explained twice), which keeps it from a 5.

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

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

Complexity here is high, but the description covers the ranking modes, the default prefetch, timeout and fallback behavior, and all five parameters; an output schema exists so return values needn't be explained. An agent could call this correctly from the description alone, with only auth/permission context missing.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate, and it largely does: it names every parameter, gives query examples, spells out the three mode values with their meanings, and adds the 'must be non-negative' constraint on context_lines. top_k and capture_id are only restated from the schema defaults, leaving marginal room to improve.

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 gives a specific verb (Searches) and resource (captured command output) plus the ranking mechanisms (BM25, Semantic, Hybrid/RRF), which lets an agent separate this from retrieval siblings like get_capture_slice or get_capture_summary. It stops short of naming those siblings to draw the boundary 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?

The description makes the mode trade-off explicit ('hybrid' is recommended, 'bm25' for keyword terms, 'semantic' for vector concepts) and states the semantic prefetch default, so mode selection is well-supported. It does not state when *not* to use this tool or how it compares to the other capture-reading tools, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a session-state mutation but does not mention side effects, repeat-call behavior, persistence, error conditions, or what happens when the feature is not enabled.

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 words. However, its brevity comes at the cost of substance, especially for the parameter.

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 annotations, no parameter documentation, and a single untyped-in-practice integer parameter, the description is far from complete. The output schema exists but does not compensate for missing parameter and behavioral semantics.

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 zero description coverage for the only parameter, max_indexed_chunks, and the description does not explain it at all. The meaning, range, units, or effect of this integer are left entirely to the agent to guess.

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

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

The description states a specific action ('Adjust this session's semantic-index chunk budget') and a precondition ('when explicitly enabled'). It is distinguishable from sibling tools that focus on captures and diagnostics, though 'chunk budget' is not elaborated.

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 only usage signal is the vague phrase 'when explicitly enabled'; there is no guidance on when to invoke this tool versus any alternative, no prerequisites, and no explanation of what 'enabled' means or how to determine it.

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

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

With no annotations, the description carries the behavioral burden, and it discloses important traits: phases are durable and sequential, completed phases are never rerun, unsafe retries require explicit approval, and outputs/history are stored under EPHEMERAL_EXECUTION_STATE_DIR. It loses a point for mentioning confirm_unsafe=True, which does not appear in the input schema, but the core behavioral story is strong.

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

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

Three sentences with no filler; the purpose is front-loaded and the phase contract is packed into a compact paragraph. The density is high, but each sentence contributes, and the structure makes the core behavior easy to absorb.

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 complex tool with 7 top-level parameters, a nested phase schema, and no annotations, this description provides a solid foundation but leaves gaps. It explains phase shape and retry semantics well but does not cover several top-level parameters and directs the agent to a non-existent confirm_unsafe parameter.

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

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

Schema description coverage is 0%, so the description must compensate; it partially does by defining the phase object and its optional fields and by referencing resume_policy. However, it omits meaningful parameters like idempotency_key, unsafe_side_effects, execution_id, label, and top-level timeout/max_output_bytes, and it references confirm_unsafe=True, which is not 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 opens with a specific verb and resource: 'Run a sequential, durably checkpointed set of command phases.' It also distinguishes this tool from its sibling resume_execution by noting that completed phases are never rerun, which helps an agent tell the starting tool apart from the continuation tool.

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

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

The description implies this is the entry point for a checkpointed pipeline and that resume_execution is the continuation path, but it never explicitly says 'use this for a fresh run; use resume_execution to continue.' It gives useful context about retrying unsafe phases, but does not clearly route the agent between alternatives.

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