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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that the tool stores a typed artifact, which implies persistence and mutation, consistent with readOnlyHint=false. No contradiction exists, but the description does not clarify further behavioral details such as overwrite semantics or handling of unsupported formats.

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 efficiently communicates the core action and result, and every word contributes meaning.

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?

Although an output schema exists and the idempotent annotation helps, the description is too thin for a tool with three parameters and a format-selection enum. It does not explain how to choose source_format, the role of benchmark_name, or what 'store the typed artifact' means in terms of side effects or artifact naming. The agent is left to infer too much.

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 carries the burden of explaining parameters, but it never mentions path, source_format, or benchmark_name. The schema's enum values and parameter names offer some self-evident meaning, but the description does not explain how source_format auto-detection works, what benchmark_name is for, or what path should point to.

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 ('normalize') and resource ('supported benchmark JSON file'), and states a concrete outcome ('store the typed artifact'). This distinguishes it from sibling analysis tools like analyze_profile or analyze_collection, which focus on different resources or operations.

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

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

The description clearly scopes the tool to benchmark JSON files and normalization/storage, so an agent can infer the general use case. However, it provides no explicit when-to-use versus alternatives, no exclusions, and no guidance on when another tool like compare_benchmarks or analyze_collection would be more appropriate.

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 convey idempotentHint=true and destructiveHint=false, but the description adds no behavioral context beyond the generic verb 'analyze.' It does not disclose whether the tool creates artifacts, mutates state, requires permissions, or has any side effects, and readOnlyHint=false leaves room for such side effects.

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

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

The description is a single front-loaded sentence with no filler or repetition. It earns its place by naming the resource, though it is slightly under-specified in terms of behavior.

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

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

The presence of an output schema covers return-value details, but the description still leaves major gaps: what analysis actually involves, when to choose this tool over an inspection or trace-analysis sibling, and whether the operation is side-effect-free. Given the large sibling set, this is not complete enough for an agent to invoke it confidently.

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 some meaning by indicating that collection_id refers to a stored CPU record collection artifact, but it does not explain how to obtain a valid ID, what format it takes, or any constraints. For a single self-named parameter this is minimally adequate but not rich.

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 ('analyze') and identifies a concrete resource ('a stored CPU record collection artifact'), so an agent can tell it operates on stored CPU record collections. However, it does not specify what kind of analysis is performed, which weakens differentiation from similar-looking sibling tools like analyze_trace_evidence or analyze_benchmark.

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

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

There is no guidance about when to use this tool versus alternatives. It does not mention context like inspecting collection capabilities, analyzing traces, verifying analyses, or building diagnosis bundles, so the agent must infer usage solely from 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 convey idempotency and non-destructiveness. The description adds the side-effect of storing JSON output, but it does not explain what 'allowed' means, whether existing output is overwritten, or any permissions needed. This is a modest addition beyond annotations with no contradiction.

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

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

The description is a single, front-loaded sentence with no filler. It earns its place, though 'allowed' is slightly ambiguous. Overall, concise and well structured.

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

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

The existing output schema partly relieves the need to describe return values, but the tool is left incomplete: no path semantics, no source_type behavior, no prerequisites, and no differentiation from analyze_collection. An agent given only this description would likely guess at required inputs.

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

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

With 0% schema description coverage, the description must explain both parameters. It partially enumerates the accepted profile kinds (folded, perf-script, perf.data), which maps to the source_type enum, but it never describes the required 'path' parameter or the 'auto' default. The hyphen/underscore mismatch between the description and the enum values further weakens clarity.

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

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

The description names a specific verb ('Analyze'), a resource ('folded, perf-script, or perf.data profile'), and an outcome ('store JSON'). It is clear enough to distinguish from collection or comparison tools, though it does not explicitly name a sibling alternative.

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 when-to-use or when-not-to-use guidance is given. It does not distinguish this tool from closely related siblings such as analyze_collection, collect_profile, or compare_profiles, leaving the agent to infer when this specific analysis is appropriate.

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 provide idempotentHint=true and destructiveHint=false but readOnlyHint=false. The description adds determinism and the verify-before-use context, which is useful. However, it does not disclose whether verification writes state, requires special permissions, or has other side effects, which matters given readOnlyHint=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?

The description is a single compact sentence that front-loads the action and resource, then adds the verification purpose. Every phrase earns its place: deterministic, stored, normalized, artifact type, and before Agent use.

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

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

For a one-parameter tool with an output schema and idempotent annotation, the description is largely complete: it states the input, the artifact type, and the intended timing. The main missing piece is clarity on side effects given readOnlyHint=false, but the output schema and annotations absorb much of the burden.

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

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

With 0% schema description coverage, the description must compensate. It references TraceEvidence artifact, making trace_evidence_id's role mostly inferable as the identifier of that artifact. But it does not explain where the ID comes from, its format, or any validation requirements, leaving a modest 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 uses a specific verb ('analyze') and identifies a precise resource: a stored, normalized sched/off-CPU/lock TraceEvidence artifact. It also adds the intended gate, 'verify it before Agent use.' However, it does not explicitly differentiate from sibling tools like verify_trace_analysis or verify_analysis, which may overlap in purpose.

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

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

The description gives clear usage context: use this tool on a stored, normalized TraceEvidence artifact before Agent consumption. It implies a precondition and timing, but it does not mention alternatives or when-not-to-use conditions, so it stops short of full routing guidance.

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

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

The description discloses meaningful behavioral traits beyond annotations: it stores a process-local secret, permits only fixed paths/recipe/modes/budgets, and explicitly enumerates actions it does not perform. This is strong transparency for an authorization tool, although it does not directly address the destructiveHint annotation or revocation 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?

Two front-loaded sentences with no filler. Every clause earns its place: the action and scope come first, followed by side-effect and boundary details. The negative action list is dense but highly useful for safe 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?

The description is strong on behavioral boundaries and side effects, and an output schema exists so return values need not be covered. However, it omits parameter semantics and usage context, which are necessary for an agent to confidently invoke this tool correctly in a workflow surrounded by many similar authorization and optimization 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It does not explain preview_id, preview_content_sha256, authorization_summary_sha256, or the authorization constant beyond their names. An agent gets no additional meaning from the description to fill these required parameters correctly.

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 ('Authorize'), a specific resource ('exact Docker optimization Preview'), and a one-time scope ('once'). The negative boundary — 'does not itself build, run, profile, modify source, commit, push, tag, or release' — clearly distinguishes this from build/run siblings like build_docker_optimization_candidate.

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

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

No explicit guidance is given about when to use this tool versus siblings such as authorize_docker_session or preview_docker_optimization_session. The phrase 'exact Docker optimization Preview once' implies a preceding preview step, but the description does not state the intended workflow, prerequisites, or 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?

Even with destructiveHint=true and readOnlyHint=false, the description adds substantial detail: it stores only process-local authorization, does not execute or profile the target, requires a fresh user reply, and clarifies that MCP permission is not workload consent. It also explains the consequence of needing expanded modes—a new summary and fresh authorization. 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?

Four sentences, each carrying necessary compliance detail. The purpose is front-loaded in the first sentence; the remaining sentences cover critical behavioral and consent constraints without excess verbiage. Slightly dense but well-structured for a security-sensitive operation.

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

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

The description covers the essential consent workflow, mode constraints, and non-execution guarantee. An output schema exists, so return values are not the description's burden. However, it does not explicitly differentiate this from sibling authorization tools like authorize_docker_optimization_session or authorize_managed_docker_session, which could leave an agent uncertain which authorization path applies.

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 important semantics for allowed_modes (must exactly equal summary mode set, expansion requires new authorization) and for authorization (user consent phrase, not just MCP permission). However, it leaves host_pid, container_pid, container_reference, and authorization_mode completely unexplained by description, relying on their names alone.

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 states a specific action ('Authorize'), a specific resource ('one project-bound existing-container performance session'), and the scope ('project-bound', 'existing-container'). It also distinguishes itself from execution/profile tools by explicitly stating it 'does not execute or profile the target', making it clear this is only an authorization step.

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 critical usage conditions: a fresh user reply to the exact session summary is required, MCP permission is not workload consent, and allowed_modes must exactly match the summary. It does not explicitly name sibling authorization tools (e.g., authorize_docker_optimization_session) as alternatives, but the context of 'project-bound existing-container performance session' gives clear situational discrimination.

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?

Adds substantial behavioral context beyond annotations: it never builds or pulls an image, requires fresh explicit user consent, and clarifies that allowed_modes must exactly match the summary mode set. These are non-obvious constraints that materially affect invocation, and they do not contradict the destructiveHing annotation.

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 ll sentences carry information with no fluff, and the safety-critical constraints are front-loaded. The first sentence captures scope, and subsequent sentences add permissions and mode-handling rules. Slightly long four-sentence definition but still disciplined.

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 high-stakes nature and output schema presence, the description covers purpose, consent, no-build/no-pull, exact-mode requirements, and re-authorization. It does not mention how to retrieve the summary or how this relates to revoke/preview siblings, but those are inferable from context and sibling names.

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 carries the burden. It clearly explains allowed_modes semantics: required, non-empty, must exactly equal the summary set, and expansion requires new authorization. It does not describe the individual enum values, but those are self-evident in the schema, and the authorization parameter's exact const phrase is already encoded 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 precise verb ('Authorize') and a specific resource: the immutable image, command, mounts, resource limits, modes, and budget pinned in the project's Docker policy. It clearly distinguishes the 'managed' flavor from the generic sibling authorize_docker_session by emphasizing policy-pinned exactness and adding the no-build/no-pull constraint.

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

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

Gives an explicit precondition: a fresh user reply to the exact summary is required and MCP tool permission is not workload consent. It also defines when allowed_modes can be used and when re-authorization is needed, though it does not directly compare against sibling authorize tools such as authorize_docker_session or authorize_docker_optimization_session.

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

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

Annotations already indicate readOnlyHint=false and idempotentHint=true, so the description doesn't need to restate side effects. 'Store' adds that the result is persisted, and 'build' implies assembly from evidence. However, it does not disclose overwrite behavior, storage location, or any failure semantics beyond what annotations provide.

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 focused sentence with no filler. The primary action and object are front-loaded, and every word contributes meaning.

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

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

For a single-parameter tool with an output schema, the description is close to adequate, but it leaves important context implicit, such as the prerequisite analysis state, how analysis_id is obtained, and when this tool should be invoked. The annotations clarify idempotency and non-read-only behavior, but the description itself is thin.

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

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

Schema description coverage is 0%, and the description never mentions analysis_id or explains what it refers to, where it comes from, or what format it should take. The parameter name is mildly self-explanatory, but the description does not compensate for the lack of schema documentation.

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

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

The description uses a specific verb ('Build and store') and a specific resource ('full evidence-constrained diagnosis artifact'), making the core function clear. It does not explicitly differentiate it from sibling tools, but the artifact-building purpose is reasonably distinct.

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

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

The description gives no guidance on when this tool should be used, what must happen before calling it, or how it relates to siblings like collect_profile, finalize_docker_optimization_candidate, or build-related analysis tools. An agent would have to infer the appropriate invocation context.

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 flag this as destructive, so the description does not need to restate that; it adds useful context by noting that no image, command, path, build argument, network option, or Docker flag is accepted from the caller. It does not disclose what specifically gets mutated or destroyed, such as Treatment paths or cached artifacts, even though destructiveHint=true is present.

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

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

The description is two sentences with the core action front-loaded and the caller-input limitation stated immediately after. 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?

The output schema reduces the need to describe return values, and the annotations cover the destructive nature, but the description still leaves gaps around the candidate_round semantics, the session concept, and the exact workflow stage relative to finalization. For a tool with three required parameters and no schema property descriptions, this is insufficient for reliable selection and invocation.

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

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

With schema description coverage at 0%, the description must carry parameter meaning. It maps build_kind to 'baseline or next candidate' and implies session_id through 'already-authorized' context, but candidate_round is never explained and session_id is not explicitly linked. The description does not compensate for the schema's lack of property descriptions.

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

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

The description uses a specific verb ('Build') and a specific resource ('baseline or next candidate'), and clarifies that caller-supplied Docker parameters are not accepted. It does not explicitly name sibling tools, so differentiation from finalize_docker_optimization_candidate or the authorization tools is left to inference.

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 'already-authorized' implies this tool should be used after authorization, and 'baseline or next candidate' places it in the optimization workflow. However, there is no explicit statement of when to use it instead of preview, finalize, or inspect tools, and no exclusion criteria are given.

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, and destructiveHint, so the description only needs to add context beyond those. It adds two useful behavioral facts: the classification is restricted to candidates ('candidate-only') and the result is a bounded page, which connects to the limit/cursor parameters. There is no contradiction with the annotations.

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

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

The description is a single front-loaded sentence with no filler. It loses a point because 'generic candidate-only' is jargon that could be clearer, but the structure is appropriately compact.

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 is simple, and the annotations plus output schema cover safety and return shape, so the description need not repeat those. Still, the description does not clarify what 'candidate' means or how classify_hotspots relates to the many sibling hotspot/collection tools, leaving an agent to infer selection 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 description coverage is 0%, so the description must compensate for the three parameters. It only hints at pagination via 'bounded classification page' and never explains the required analysis_id, limit, or cursor semantics.

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

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

The description states an action ('Apply...rules') and a result ('return a bounded classification page'), so it is not a tautology. However, 'generic candidate-only rules' is vague and the description never explicitly names the resource ('hotspots') or distinguishes itself from siblings like get_hotspot_details and list_hotspots.

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. It does not mention get_hotspot_details, list_hotspots, or analyze_collection, and 'candidate-only' only weakly implies a scope without saying when an agent should prefer another 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?

The description adds materially to the annotations by disclosing that a failed attempt after workload-lease issuance is charged and halts further build/collection operations in the session, and that the call must not be retried unchanged. It also reassures that the caller cannot select images, commands, mounts, networks, Docker options, or host paths, which is meaningful beyond destructiveHint=true.

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

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

Three sentences, each earning its place: purpose, caller constraints, and critical failure/retry behavior. The key action is front-loaded and there is no filler.

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

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

Despite an available output schema and annotations, the tool has 10 parameters with 0% schema coverage and no per-parameter explanation in the description. The high-level safety and session-blocking behavior is covered, but the agent cannot correctly choose values for mode, event_source, call_graph, or the time/output bounds without external knowledge.

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 carries the burden of explaining parameters. It only implies that inputs are 'bounded evidence' and vaguely maps session/Build to session_id/build_id; it does not explain mode, events, call_graph, event_source, frequency_hz, duration_seconds, max_output_bytes, or workload_timeout_seconds.

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 operation: run and collect bounded evidence from a verified image Build tied to a one-confirmation optimization session. It also explicitly scopes what the tool is not for ('never an image, command, mount, network, Docker option, or host path'), which differentiates it from sibling collection tools like collect_docker_target and collect_managed_docker_workload.

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 only for a verified Build from a one-confirmation optimization session, and the caller chooses bounded evidence rather than arbitrary Docker inputs. It does not explicitly name alternative tools or state 'use X instead', but the constraints are strong enough to infer when this tool is appropriate.

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 carry destructiveHint=true, and the description's 'consume one bounded session run' reinforces that the operation is state-consuming rather than benign. It adds extra behavioral context beyond annotations: the data is collected 'through the restricted Broker' and 'the Docker adapter never enters the Collector or Helper,' which clarifies the architectural path and constraints. 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 only two sentences with no filler, and the main action is front-loaded ('Re-resolve... consume... collect...'). Each sentence contributes a distinct piece of information. It loses half a point because the dense, undefined jargon ('bounded session run', 'restricted Broker', 'Collector', 'Helper') makes the compactness harder to parse.

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 11 parameters, zero schema coverage, and a destructive side effect, the description is far from complete. It does not explain what 'collect' returns, what 'bounded session run' means, how authorization is checked, or how to map inputs to the desired collection behavior. The output schema and annotations cover some risk signals, but an agent would still struggle to invoke this tool correctly without additional 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 description coverage is 0%, so the description carries the full burden of explaining parameters, but it mentions none of the 11 parameters: no guidance for mode, events, call_graph, frequency_hz, duration_seconds, host_pid, container_pid, or max_output_bytes. The only weak link is that 'authorized existing-container process' loosely maps to container_reference, but this is far too generic to help an agent choose correct values.

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 specific verbs ('re-resolve', 'consume', 'collect') and a concrete resource ('authorized existing-container process' via 'restricted Broker'), so an agent can tell this tool collects data from a Docker container process already authorized. It does not name a sibling tool, but the scoping language ('authorized', 'bounded session run') and the Broker/Collector/Helper routing hint differentiate it from the broader collection tools. The meaning is somewhat jargony but not a tautology.

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

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

It implies usage for an already-authorized existing-container process and a bounded session run, giving some contextual conditions. However, it does not state when to prefer this over siblings like collect_docker_optimization_workload, collect_managed_docker_workload, or collect_profile, and there are no explicit when-not-to-use or alternative-naming guidelines.

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

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

The description adds useful behavior beyond the destructiveHint annotation: it creates a temporary container, waits for Broker readiness, and explicitly cleans only the verified container, scoping the destruction conservatively. It also implies blocking behavior with 'wait.' No contradiction with annotations exists.

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

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

The description is a single dense sentence with no filler; every clause adds a behavioral or scoping constraint. However, the run-on structure and heavy jargon make it less immediately scannable than ideal.

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 lifecycle is described and an output schema exists, but for a 9-parameter destructive tool with no parameter descriptions and no usage guidance, the description is not sufficient for an agent to confidently select the right configuration. It lacks session prerequisites, parameter semantics, and clear routing among many sibling collection 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 input schema has 0% description coverage across 9 parameters, and the description does not mention any parameter name or concept such as mode, events, call graph, frequency, duration, output limits, or timeout. It also does not clarify what session_id refers to, leaving parameter meaning almost entirely to inference from names, enums, and defaults.

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 concrete lifecycle: it creates one temporary container from an already-local immutable image, holds the workload at the package Gate, runs/collects, waits, and conservatively cleans only that verified container. This gives a clear verb/resource pair and includes enough detail to distinguish this managed collection workflow from sibling collection 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?

The description implies a precondition with 'already-local immutable image' and 'until Broker collection is ready,' but it never explicitly tells an agent when to choose this tool over alternatives such as collect_docker_optimization_workload or collect_docker_target. No exclusions or comparison guidance is provided.

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

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

Given the destructiveHint=true annotation, the description adds useful context by emphasizing bounded collection and the need for explicit server and per-call authorization. However, it does not disclose what the destructive behavior actually consists of, such as what happens to output_path or what side effects attaching perf to a process may have.

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, front-loading the action and scoping it to bounded perf collection before stating the authorization gate. 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?

The output schema lightens return-value expectations, but this is a destructive 13-parameter tool with 35 siblings and zero schema descriptions. The definition omits prerequisite/alternative guidance and key parameter-selection semantics, so an agent cannot confidently invoke it correctly from this description alone.

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 carries the full burden for parameter meaning, but it only hints at the mode values ('record/stat/sched/lock/off-CPU') and the authorization requirement. It leaves pid vs. executable vs. target_arguments selection, call_graph tradeoffs, duration/timeout semantics, and output_path expectations 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?

The description is specific: it names the verb ('Run'), the resource class (bounded perf record/stat/sched/lock/off-CPU collection), and the authorization prerequisite. This clearly differentiates it from the docker- and project-level collect_* siblings, which collect different kinds of data.

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 guidance is the precondition that explicit server and per-call authorization must exist before invoking the tool. There is no when-to-use-this-vs-alternatives guidance, no mention of the many sibling collect/analyze tools, and no exclusions or fallback paths.

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

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

The description adds meaningful behavioral context beyond the destructiveHint annotation: it actually runs an executable, binds to a specific PID incarnation, routes collection through a restricted broker, and demands exact authorization. The warning against substituting manual PID attachment is especially useful for safe invocation.

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

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

The description is compact and front-loaded with the core action. Both sentences earn their place: the first states what the tool does, and the second enforces the mandatory authorization contract. There is no filler.

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

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

The description covers the critical safety context and the required authorization flow, and an output schema exists to describe return values. However, with 11 parameters, destructive behavior, and zero parameter-level schema documentation, the definition is not fully self-sufficient for an agent to invoke it correctly in varied scenarios.

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 carry the burden of explaining 11 parameters. It only addresses authorization, executable, project root, and PID attachment. The many tuning parameters (mode, events, call_graph, event_source, frequency_hz, duration_seconds, max_output_bytes) are left entirely 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?

The description states a specific action: run one explicitly authorized executable in a project, bind its exact PID incarnation, and collect it through the restricted Collector broker. This clearly distinguishes it from sibling Docker-focused collection tools and makes the tool's scope obvious.

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: the tool should be used after the user approves the exact execution scope, and it must use the exact authorization constant. It does not explicitly name alternatives or say when not to use it, but the 'inside a project' framing and authorization requirement provide strong situational guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds the notion of 'condition and impact checks,' but does not explain what those checks do or whether any state changes occur. No contradiction exists, but the added behavioral context is thin.

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, front-loaded sentence with no filler. It communicates the primary action immediately, though the brevity also causes some ambiguity in the checks and usage conditions.

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?

Even with an output schema available, the description omits key decision-making context: when to use this compare tool versus sibling compare tools, what 'condition and impact checks' mean, and how the minimum practical impact threshold behaves. It is too sparse for an agent to confidently invoke without additional inference.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It does not explain baseline_benchmark_id, candidate_benchmark_id, or minimum_practical_impact_percent. The parameter names are partly self-explanatory and 'impact checks' loosely hints at the threshold parameter, but this is not enough.

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: 'Compare repeated benchmark values with condition and impact checks.' This identifies the core operation and distinguishes it from profile/container comparison tools, though 'condition and impact checks' remains somewhat vague.

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

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

No guidance is given about when to use this tool over siblings like compare_profiles, compare_container_measurements, or compare_docker_optimization_iterations. The description does not specify when baseline/candidate comparisons are appropriate or what makes this tool the right choice.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, but the description adds no information about side effects, authorization requirements, failure modes, or what the comparison actually produces. The evidence-type list is semantic context, not behavioral disclosure. 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 immediately, though the long list of evidence types makes it dense and somewhat jargon-heavy.

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

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

An output schema exists, so return-value documentation is partly covered. However, with six required ID parameters and zero property descriptions, the description does not explain how to obtain or select those IDs, what 'bound profile' or 'treatment' evidence means, or how the optional thresholds affect behavior. This is insufficient for reliable 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%, and the description does not explain any of the eight parameters. The evidence categories mentioned (profile, benchmark, correctness, treatment, resource) only vaguely map to the required measurement, analysis, and benchmark IDs, and the optional threshold parameters minimum_delta_percent and minimum_practical_impact_percent are left entirely 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?

The description states a specific action and resource: 'Compare two Docker measurements' and enumerates the evidence dimensions involved (bound profile, absolute benchmark, correctness, treatment, whole-container resource). This is clearer than a tautology and helps distinguish it from profile-only or benchmark-only siblings, but it does not explicitly differentiate it from the similarly named compare_docker_optimization_iterations.

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 such as compare_profiles, compare_benchmarks, or compare_docker_optimization_iterations. The phrasing implies it is for comparing container measurement evidence, but no explicit when-to-use or when-not-to-use boundaries 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?

The description adds behavioral context beyond the annotations: it is deterministic, requires an authorized pair, and treats differing image digests as session-bound Treatment evidence rather than as a simple comparison failure. This is meaningful supplementary behavior that the annotations alone do not express.

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

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

The description is compact, front-loaded with the primary action, and contains no filler. The second sentence adds an important acceptance constraint, though the phrasing is dense and somewhat jargon-heavy.

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

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

For a tool with 11 parameters, 9 required, and no parameter descriptions, the description is not complete enough to guide correct invocation. It does not explain where the IDs come from, how the thresholds behave, or what qualifies as 'authorized'. The presence of an output schema helps, but it does not compensate for the missing parameter and workflow 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 description coverage is 0%, so the description must compensate, but it does not explain the individual parameters. It references baseline/candidate build, measurement, analysis, and benchmark IDs only conceptually, and it never defines minimum_delta_percent or minimum_practical_impact_percent. The parameter names are suggestive but not sufficient.

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

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

The description states a specific verb ('compare'), a specific resource ('one authorized baseline/candidate Build pair'), and the dimensions involved (container measurements, profiles, Benchmark correctness, resource deltas, invariants). This clearly distinguishes it from the more narrow sibling tools like compare_profiles, compare_benchmarks, and compare_container_measurements.

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

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

No explicit guidance is given about when to use this tool versus the many comparison siblings. The description implies this is for comparing optimization iterations within an authorized session, but it never states when an agent should choose this over compare_profiles, compare_benchmarks, or compare_container_measurements.

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 convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that the tool stores evidence, which is a useful non-obvious side effect, but it does not explain what 'bounded profile-difference evidence' means or what exactly gets persisted.

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 redundancy. However, the phrase 'bounded profile-difference evidence' is vague jargon that could have been simplified, so it is concise but not maximally clear.

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 there is an output schema, returning values need not be explained, but the description still leaves significant gaps: parameter semantics (especially minimum_delta_percent), how 'evidence' is stored, and when this tool should be selected over sibling compare tools. This is under-specified for safe 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%, so the description must compensate. It only implies baseline_analysis_id and candidate_analysis_id refer to the two stored analyses, but it does not clarify their roles or explain minimum_delta_percent at all, leaving an optional threshold parameter 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 description states a clear verb ('Compare') and resource ('two stored analyses'), and adds that it stores 'bounded profile-difference evidence,' which distinguishes it from pure comparison tools. It does not explicitly name sibling tools, so it narrowly misses 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?

No guidance is given about when to use compare_profiles versus alternatives like compare_benchmarks, compare_container_measurements, or compare_docker_optimization_iterations. The agent must infer the intended context from the tool name and vague phrase 'stored analyses.'

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, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond that: the observation is bounded, the container must already exist and be local, and only a narrow set of fields is returned. 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?

One dense sentence with no filler. Every clause earns its place: scope is stated, boundedness is explicit, and the limited return set is front-loaded. This is an appropriately concise tool description.

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?

There is an output schema, so return-value details do not need to be repeated. Annotations cover the read-only/idempotent safety profile, and the description communicates the core constraints. Minor gap: it does not mention failure cases like a nonexistent container, but that is not critical for a simple local observation tool.

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

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

Schema description coverage is 0%, so the description must compensate. It indirectly clarifies container_reference as an existing local container and observation_duration_ms as the bound on CPU observation, but it does not explain accepted formats, valid ranges, or how the default interacts with behavior. For only two simple parameters this is adequate but not thorough.

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 ('Observe') and clearly identifies the resource: bounded CPU deltas for one existing local container. It also specifies the exact output fields, which makes the tool's function unambiguous and distinct from broader Docker collection or optimization 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?

The description implies the tool is for a single, existing local container and for bounded CPU observation, but it never explicitly states when to use this tool instead of the many sibling tools. There are no exclusions or named alternatives, so the agent must infer when this is the right tool.

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

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

Annotations already indicate destructive, non-idempotent behavior, and the description adds beyond that by disclosing that the plan is consumed after one use and that a restricted broker is involved. This gives the agent useful operational context about side effects and access constraints without contradicting the annotations.

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

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

The description is a single sentence with no filler. It front-loads the verb and object, then adds the two most important operational constraints: the restricted broker and the short-lived/single-use nature of plans.

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

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

For a one-parameter destructive action with an output schema and relevant annotations, the description covers plan lifecycle and access restrictions well. The main minor gap is that the term 'PID' is not expanded, but the simple input and presence of an output schema keep this from being a significant completeness issue.

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 only exposes a required string plan_id with the title 'Plan Id', and schema description coverage is 0%. The description adds lifecycle meaning by characterizing the plan as previously planned, short-lived, and single-use, but it does not explicitly say how to obtain the plan_id or what format it takes. This is adequate for a single simple parameter but not fully compensating for zero schema coverage.

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

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

The description identifies a specific action ('Execute'), a specific object ('one previously planned PID collection'), and a distinguishing delivery mechanism ('restricted collector broker'). It clearly differentiates this tool from planning and direct collection siblings by emphasizing that execution applies only to previously planned, single-use plans.

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

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

It states the tool is appropriate only for collections that were previously planned, and adds that plans are short-lived and single-use, implying the agent should not attempt to reuse a plan. It does not explicitly name an alternative tool for creating plans, but the context is clear enough for correct selection.

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

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

The description discloses useful behavioral traits: it revokes the session, cleans only verified session resources, and never creates or upgrades an A/B conclusion. However, it says 'clean only verified session resources,' which implies removal or deletion, while the annotations declare destructiveHint=false. That is a direct contradiction with the declared 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 compact and information-dense: every phrase adds scope, conditions, side effects, or safety caveats. The first sentence is somewhat overloaded, but it still front-loads the main action and remains clear.

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 six parameters, zero schema coverage, and an output schema, but the description does not explain how to map disposition, when to supply iteration_id, or how authorization should be set. It also lacks explicit guidance on alternatives and exclusions, so an agent would still struggle to invoke this tool correctly despite the rich behavioral 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 description coverage is 0%, so the description carries the full burden of explaining the six parameters, but it never names session_id, disposition, iteration_id, authorization, evaluation_reason, or candidate_build_id. It indirectly hints at authorization via 'fresh explicit user decision' and at evaluation_reason via 'could not be evaluated,' but this is insufficient for an agent to reliably construct the arguments.

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

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

The description names a specific verb ('Finalize'), a concrete resource ('source-workspace choice'), and the exact triggering conditions ('one replay-verified Iteration' or 'a stopped Session whose latest candidate could not be evaluated'). It also distinguishes its composite behavior from sibling tools like revoke_docker_optimization_session by combining finalization, revocation, and cleanup.

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 explicitly states the two scenarios in which the tool should be used, and warns that retaining a non-verified candidate requires a fresh explicit user decision. It does not name alternative tools or give direct 'do not use when' exclusions, but the usage envelope is clearly bounded.

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, and destructiveHint false, covering safety. The description adds behavioral context that results are page-limited and can be filtered by symbol, which goes beyond annotations. However, it does not disclose ordering, the meaning of 'dominant', or pagination cursor behavior; this is acceptable given the annotations but not rich.

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 and free of filler. Every phrase earns its place, though it is minimal and leaves several details to the schema.

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

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

With an output schema and annotations present, return values and safety are covered. The description is adequate for a simple read-only paginated query: it names the resource, mentions pagination, and the optional symbol filter. However, it lacks pagination/cursor semantics, ordering details, and usage routing among siblings, leaving moderate 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 mentions the symbol filter and the notion of a bounded page, but does not explain cursor mechanics, limit defaults, or that analysis_id is a required identifier. This leaves the agent with only the raw schema names and defaults for parameter understanding.

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'), a specific resource ('bounded page of dominant call paths'), and an optional filter ('containing a symbol'). It clearly identifies what the tool does and distinguishes it as a paginated call-path query. It does not explicitly differentiate from siblings like get_hotspot_details, but the resource is specific enough.

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 siblings such as get_hotspot_details, analyze_trace_evidence, or list_hotspots. The description implies pagination with 'bounded page' but does not explain typical usage flow, prerequisites, or when the symbol filter is appropriate.

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 'bounded dominant paths' and 'limits', hinting at output size constraints, but it is vague and doesn't specify how call_path_limit affects the returned data.

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

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

The description is a single sentence with no wasted words and places the core purpose first. However, its brevity sacrifices important semantic detail, making it under-specified rather than appropriately concise.

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

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

Output schema and annotations fill in return shape and safety, but the description leaves usage context and parameter semantics largely open. For a simple 3-parameter read-only tool this is a minimally viable definition, but it still has clear gaps in guidance and parameter clarity.

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, but it only alludes to 'limits' without explaining analysis_id, hotspot_id, or call_path_limit. These parameter roles are not described with enough clarity for an agent to confidently populate them.

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'), a specific resource ('one hotspot'), and the content the caller receives, but it doesn't explicitly differentiate this from siblings like list_hotspots or get_call_paths beyond the singular scope.

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 use this tool vs alternatives. It never mentions list_hotspots, get_call_paths, classify_hotspots, or any prerequisite analysis step, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds the key constraint that it operates 'within one configured allowed workspace', which is a behavioral boundary not captured by annotations. It also says 'bounded source lines', implying it reads a limited range rather than an entire file, adding contextual value.

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, well-structured sentence that communicates the core function immediately. It is front-loaded with the verb 'Read' and contains no unnecessary words. Every word contributes to the meaning.

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 concise but leaves several gaps: no usage differentiation from sibling tools, no parameter semantics beyond what the names imply, and no information about constraints like error handling when workspace_root is not configured. However, the annotations and the presence of an output schema mitigate some of these gaps, making the tool minimally viable but lacking in contextual richness for an agent navigating a complex toolset.

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

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

Schema description coverage is 0%, so the description must compensate for parameter semantics. The description only gives a high-level idea ('bounded source lines') and does not explain the roles of 'file', 'line', 'before', 'after', or 'workspace_root'. While parameter names are somewhat self-explanatory, the description fails to clarify the relationship between 'line' and the before/after values, or the significance of 'workspace_root' as a security boundary.

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 the specific verb 'Read' and the resource 'bounded source lines', clearly indicating the tool reads a limited range of lines from a file. The clause 'within one configured allowed workspace' adds scope and constraint. However, it does not explicitly distinguish from sibling tools like read_artifact_page or resolve_source, though the 'bounded' and 'workspace' wording hints at its unique purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of use cases, exclusions, or references to sibling tools. Users must rely on the name and the brief description alone, which is insufficient for making an informed choice among the many siblings.

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 description does not need to repeat safety. It adds value by explicitly stating 'without sampling or attaching to a process,' which is a meaningful behavioral trait beyond the annotations. No contradiction exists.

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

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

One compact, front-loaded sentence: the verb comes first, the scope follows, and the key contrast ('without sampling or attaching') is included at the end without verbosity. 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?

For a zero-parameter, side-effect-free inspection tool, this description is complete. The output schema is available for return-value expectations, annotations cover the safety profile, and the description sufficiently explains what capabilities are being inspected. Nothing needed to select and call the tool is missing.

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

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

The tool takes zero parameters, so the 100% schema coverage is trivially complete. The description's list of inspectable areas (perf, kernel policy, capabilities, collection-mode availability) defines what is surfaced at runtime, which compensates for the lack of any parameter-level documentation. Baseline for zero params is 4; description is consistent with that.

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

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

The description names a specific verb ('Inspect'), multiple concrete resources (perf, kernel policy, capabilities, collection-mode availability), and immediately distinguishes the tool by stating it does so 'without sampling or attaching to a process.' This is far more differentiating than typical boilerplate and clearly identifies what the tool does.

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 'without sampling or attaching to a process' establishes a use context: call this when you need capability information without performing side-effecting collection actions. It is not as strong as naming an explicit alternative sibling, but it gives clear contextual guidance about when this tool is the right choice.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful context by specifying the fixed local endpoint and cgroup-v2 focus, and by confirming that no container lifecycle operations are performed. This goes beyond the annotations without contradicting them.

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, tightly worded sentence. It front-loads the tool's purpose and immediately conveys its non-invasive scope without unnecessary elaboration.

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 tool with a rich annotation set and an output schema, the description is complete. It tells the agent exactly what scope is inspected and what side effects are avoided, which is sufficient to select and invoke the tool 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, so parameter semantics are not a concern. Schema coverage is 100%, 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 verb 'inspect' and the specific resources (local Docker endpoint and cgroup-v2 support). It also differentiates the tool from sibling inspection tools by explicitly saying it does not start, stop, build, pull, or profile containers.

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

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

The description implies this tool is for safe, read-only inspection by listing what it avoids, but it does not explicitly state when to choose this tool over sibling inspection tools or when not to use it. The usage context is clear, but alternatives and exclusion criteria are not directly addressed.

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, and destructiveHint=false. The description adds useful behavioral specificity by stating it 'never builds, pulls, runs, profiles, or modifies source' and clarifying the scope is 'fixed local,' which aligns with openWorldHint=false. No contradiction.

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

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

Two sentences, front-loaded with the inspection scope and followed by a concise side-effect guarantee. Every sentence adds value and there is no filler.

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

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

For a no-parameter, read-only inspection tool, this description is complete: it enumerates what is inspected, states that it is non-mutating, and the output schema covers return structure. The only minor gap is explicit sibling differentiation, which is not critical given the clear scope.

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

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

The tool has zero parameters and schema coverage is 100%, so the description has little parameter burden. It appropriately focuses on what the inspection covers rather than argument syntax.

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 clear inspection verb with a specific, enumerated resource scope: fixed local Docker/Buildx/Builder identities, project build contract, Benchmark requirement, base-image presence, and Collector modes. This distinguishes it from sibling inspection tools like inspect_docker_capability and inspect_collection_capabilities.

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 a read-only pre-flight inspection role but does not explicitly state when to use this tool over alternatives such as inspect_docker_capability or preview_docker_optimization_session. No exclusions or sibling comparisons 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 disclose readOnly, idempotent, non-destructive behavior, so the description does not need to repeat those traits. It adds the useful 'bounded page' behavioral detail but says nothing about sort_defaults, filter behavior, cursor semantics, or what happens when the page is exhausted. This is acceptable but not rich.

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 no redundant filler. The core action and resource are front-loaded, and every word contributes meaning.

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?

Despite a strong annotation set and output schema, the tool has five parameters involving pagination, filtering, and sorting, and the description does not explain any of them. It also lacks usage guidance relative to sibling tools, leaving the agent to infer important selection and invocation 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 description coverage is 0%, and the description does not explain limit, cursor, sort_by, category, or analysis_id beyond implying pagination via 'bounded page'. The schema provides defaults and an enum, but the description adds no meaning for the filter and sorting parameters, so it fails to compensate for the coverage gap.

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

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

The description clearly names a specific verb ('Return') and resource ('a bounded page of hotspots from a stored analysis'), and the 'bounded page' wording signals pagination rather than detail retrieval. It does not explicitly contrast with sibling tools such as get_hotspot_details or classify_hotspots, so it falls just short of full sibling differentiation.

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 'from a stored analysis' implies the tool should be used after an analysis has been saved, but there is no explicit when-to-use guidance, prerequisite mention, or direction to alternatives like get_hotspot_details for a single hotspot. Usage context is only implied, not stated.

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

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

Annotations already cover read-only and idempotent behavior, and the description adds useful context beyond that: the plan is short-lived, PID-bound, and has no sampling/attach side effects. This gives the agent a clear behavioral model without contradicting the annotations.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the clarifying non-goal sentence earns its place by preventing misuse.

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 output schema and annotations cover safety and return structure, and the description gives a clear enough role for a planning operation. However, with 0% parameter documentation and no explicit pointer to execute_collection_plan, an agent is left without enough guidance for correct invocation in a broader workflow.

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, but it only clarifies that the plan is PID-bound. It does not explain mode, events, call_graph, event_source, frequency_hz, duration_seconds, or max_output_bytes, leaving the agent to infer meaning from parameter names and defaults alone.

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 ('Create') and a specific resource ('short-lived PID-bound collection plan'), and explicitly states what it does not do ('does not sample or attach'). This clearly distinguishes it from execution and collection siblings like execute_collection_plan and collect_profile.

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 scope clear: this tool only creates a plan, not sample or attach. This gives an implicit boundary against execution/collection tools, but it does not explicitly name alternatives or state 'use execute_collection_plan when you are ready to run the plan.'

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 provide idempotentHint and destructiveHint, and the description adds useful behavioral context: no build/pull side effects and a mandatory user confirmation gate before authorization. This goes beyond the structured annotations and helps an agent understand the tool's non-obvious workflow role.

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 short and front-loads the main action and constraints. However, phrases like 'exact authorized build context' and 'content-bound one-confirmation optimization summary' are needlessly opaque and could be clearer without adding length.

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 output schema likely covers return value structure, so that is not a gap. But the required allowed_modes parameter is completely unexplained, and the description only weakly situates this tool in the broader workflow. The 'must confirm before authorization' line helps, but it is not enough for confident invocation.

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

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

The input schema has one required parameter, allowed_modes, with 0% schema description coverage, yet the description never mentions it or explains how to choose among stat, record, sched, off_cpu, and lock. The agent is left to infer the meaning of 'authorized build context' and cannot reliably populate the required parameter.

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

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

The description states a concrete action ('Capture... and return... summary') and a clear resource (docker optimization session), with explicit non-goals ('does not build or pull'). The meaning is somewhat obscured by jargon like 'content-bound one-confirmation optimization summary,' but it is generally distinguishable from build/authorize siblings.

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

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

The description clearly indicates this is a preview step: 'The user must confirm this exact Preview before authorization.' It also excludes build/pull use cases, which helps an agent choose it over build_docker_optimization_candidate or authorize_docker_optimization_session, though it never names those alternatives explicitly.

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 the tool read-only, idempotent, and non-destructive, so the description only needs to add context beyond that. It usefully adds the 64 KiB cap, but it does not explain how offset/limit paging works across larger artifacts or what happens when reading past the end.

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 contributes meaning, which is appropriate for this simple read operation.

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 output schema and annotations cover return values and safety, so the description does not need to repeat those. However, for a paginated artifact reader, the omission of offset/limit behavior is a meaningful gap that an agent would need to infer.

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, but it only implicitly references the limit via '64 KiB'. It does not explain artifact_id, artifact_type, or offset semantics, and the enum values in the schema are left entirely for the agent to interpret.

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 specific operation ('Read'), a concrete resource ('stored JSON artifact'), and a clear bound ('at most 64 KiB'). This is enough for an agent to distinguish it from the sibling tools, which mostly focus on collection, analysis, and optimization rather than direct artifact paging.

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

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

No guidance is given about when to use this tool versus alternatives. The description does not mention intended scenarios, exclusions, or how it relates to other read/inspection tools.

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, and non-destructive behavior, so the bar is lower. The description adds useful context beyond annotations by naming the sources consulted (Docker, /proc, PID start time, namespaces, cgroup identity, UID policy) and explicitly stating that profiling is not performed. It does not address failure cases, but this is consistent with the safe read-only 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 one dense sentence with the action front-loaded and no filler. Every phrase contributes to defining the operation, though the long list of resolution sources makes it somewhat heavy to parse. It is concise without being under-specified.

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 output schema covers return values and annotations cover safety, but the description omits usage conditions and optional-parameter semantics. In a large sibling set, an agent still lacks clear guidance on when this should be called instead of collection, discovery, or profiling tools, making the definition incomplete for confident 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%, so the description must compensate, but it never explains the relationship or selection logic for host_pid, container_pid, and container_reference. It mentions PID start time as a resolution criterion but does not map that to the parameters. The property names are partly self-explanatory, but the description does not add meaningful parameter-level guidance.

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

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

The description states a specific action ('Re-resolve'), a bounded resource ('one container process'), and a precise set of resolution criteria (Docker, /proc, PID start time, namespaces, cgroup identity, UID policy). The phrase 'without profiling it' distinguishes it from profiling- and collection-oriented siblings. It is not a 5 because 're-resolve' itself is not defined, leaving some ambiguity about what the operation produces.

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 explicit guidance on when to use this tool versus alternatives such as collect_docker_target, discover_docker_processes, or analyze_profile. 'Re-resolve' weakly implies a follow-up to an earlier resolution, and 'without profiling it' implies a lightweight purpose, but the agent is left to infer the actual selection conditions.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, which covers the main behavioral safety profile. The description adds minor context with 'verified' and 'allowed', implying that the offset must be pre-validated and the file must be whitelisted, but it does not detail error behavior, permissions requirements, or side effects. Since annotations are strong and the description adds some useful nuance, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence that efficiently states the core action. It is appropriately brief and avoids fluff, but its brevity is at the expense of completeness. For a concise description, it does its job, though it could be slightly expanded without losing efficiency.

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 that the tool has no schema descriptions and appears to be part of a larger profiling workflow, a one-sentence description is insufficient. It does not explain the role of the tool relative to siblings like 'get_source_context', the prerequisites for using it, or what the output represents. While an output schema exists, the description itself leaves too much undefined for an agent to confidently invoke the tool 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?

With 0% schema description coverage, the description must compensate for the lack of parameter documentation. It loosely references 'module offset' and 'ELF/debug file', which map to module_offset and binary_path, but it omits any explanation of runtime_address, which is an optional but potentially important parameter. It also does not clarify the meaning of 'verified' or 'allowed' in relation to the inputs, leaving significant semantic gaps.

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 ('resolve') and a resource ('verified module offset'), but the meaning of 'resolve' is ambiguous—it could mean mapping an offset to a source line, a symbol, or something else. It does not clearly differentiate from sibling tools like 'get_source_context', which likely overlaps in functionality. The phrase 'allowed ELF/debug file' adds context but not enough to fully clarify the tool's purpose.

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

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

The description offers no explicit guidance on when to use this tool versus alternatives like 'get_source_context' or 'analyze_profile'. It does not mention prerequisites, such as verifying the offset or obtaining an allowed file list, nor does it state exclusions or typical use cases. The only implicit guidance is the focus on 'verified' and 'allowed' inputs, which is insufficient.

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?

Adds valuable behavioral detail beyond annotations: the operation revokes exactly 'one' authorization and cleans only 'verified session-owned temporary image tags and private snapshots'. This clarifies what may be removed while staying consistent with destructiveHint=false because the cleanup is conservatively scoped to ephemeral session-owned artifacts and idempotentHint=true.

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 densely packed sentence front-loads the primary action and then adds a precise scope qualifer. No fluff, no repetition of structured fields, and every clause earns its place.

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

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

For a single-parameter tool with an output schema and annotations covering idempotency/destructivity, the description is largely complete: it names the resource type, the action, and the exact cleanup boundary. It could additionally reference the authorize_docker_optimization_session sibling or state a prerequisite, but that gap is minor.

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

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

The schema has 0% description coverage for session_id, so the description must carry meaning about the parameter. The description indirectly identifies session_id as the optimization session whose authorization is revoked and whose artifacts are cleaned, but it never explicitly defines the field or says where to obtain its value.

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 ('Revoke') and resource ('one in-memory Docker optimization authorization'), then specifies the cleanup scope: only verified session-owned temporary image tags and private snapshots. The 'optimization' qualifier clearly distinguishes it from sibling revoke_docker_session.

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

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

The intended use is implied by the name and description: call this when an optimization session authorization needs to be revoked. However, it does not explicitly state when to use it versus alternatives, mention prerequisites, or rule out the sibling revoke_docker_session.

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