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

Beyond the destructiveHint annotation, the description discloses significant behavioral context: the VITRON-EA1 policy gate remains armed, subsequent tell() calls will be blocked with reason KILL_SWITCH_ACTIVE, and this state persists until reset. This gives the agent a clear picture of the tool's side effects and lasting impact.

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

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

The description is three sentences, front-loaded with the primary action, then the behavioral consequence, then the usage guidance. Every sentence provides essential information with no redundancy.

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

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

The description covers the action, immediate effect, post-activation state, reset condition, and specific use cases. For a kill switch with no output schema, this is complete and leaves no major gaps in the agent's understanding.

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 already fully describes the optional 'reason' parameter as 'Optional explanation that lands in the audit trail for later review.' The tool description does not add any additional semantic detail beyond the schema, so the baseline score of 3 applies.

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

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

The description begins with 'Halt all current and queued automation immediately,' which is a specific verb and resource that clearly defines the tool's action. It distinguishes from sibling tools like alethia_status or alethia_tell by focusing on the kill switch functionality.

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 lists when to use the tool: when an agent is acting unsafely, when human review is required, or to enforce a hard boundary at the end of a controlled test run. However, it does not mention when not to use it or point to alternative tools, so it falls just short of a 5.

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

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

Annotations already indicate read-only and non-destructive. The description adds that it returns a per-action report with block/allow status and that it verifies blocks without performing clicks, providing behavioral context beyond the annotations. 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, each providing distinct value: what it does and when to use it. Every sentence earns its place with no wasted words.

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

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

Despite lacking an output schema, the description explicitly states the return format (per-action report with block/allow status). The single parameter is well-documented, and annotations cover the safety profile, making the description complete for this tool.

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

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

The schema fully describes the single 'url' parameter, so the description adds little beyond restating that it navigates to a URL. Baseline of 3 is appropriate when schema coverage is complete.

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 ('navigate', 'discover', 'verify') and clearly identifies the resource (every destructive/write-high action on a page) and the VITRON-EA1 policy gate. It distinguishes from sibling audit tools by framing this as policy verification rather than accessibility/NIST audits.

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

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

Explicitly states when to use: 'Use it as a compliance check before releasing an agent-driven workflow against a customer environment.' It also implies it is the automated alternative to manually clicking destructive buttons, providing clear 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 declare readOnlyHint=true and destructiveHint=false, establishing safety. The description adds context beyond this: it operates on 'the current page', checks 8 specified controls across 3 families, and returns findings with control IDs and severity levels. This gives the agent a clear model of what the tool does without contradicting the read-only hint.

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

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

The description is composed of three concise sentences: the first states the core action, the second details the specific controls, and the third gives usage guidance and output expectations. Every sentence earns its place with relevant information and no redundancy.

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

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

With no output schema, the description appropriately mentions 'Returns findings with control IDs and severity levels,' covering return value expectations. It also explains the scope and usage context. It does not describe edge cases or prerequisites beyond navigation, but for a zero-parameter, read-only audit tool, this is a solid and complete description.

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

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

The tool has zero parameters, and schema coverage is 100% (vacuously). With 0 params, the baseline is 4. The description explains the tool's behavior and output even though there are no parameters to document, providing sufficient semantic context for invocation.

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

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

The description opens with a specific verb+resource+scope: 'Run a NIST SP 800-53 Rev. 5 web application security controls audit on the current page.' It clearly states the standard (NIST SP 800-53 Rev. 5), the target (current page), and lists the exact control families (AC, IA, SI) with sample checks. This distinguishes it from the sibling alethia_audit_wcag by specifying a distinct standard and domain.

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

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

The instruction 'Call after navigating with alethia_tell' provides an explicit when-to-use context. It also implies the tool is for security audits, differentiating it from accessibility audits (alethia_audit_wcag). However, it does not explicitly mention when-not-to-use or alternative tools by name, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it operates on the current page, is powered by axe-core, covers a dynamic ruleset rather than a fixed checklist, and returns findings with rule IDs, impact levels, and issue counts. This goes well beyond 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 three sentences, with the main action front-loaded in the first sentence. Every sentence contributes: what it does, what it checks, and when to call it plus return format. 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?

For a zero-parameter, read-only tool with annotations and no output schema, the description fully covers purpose, behavior, usage timing, and return value. It also distinguishes from the NIST audit sibling, making it complete for an agent to select and invoke 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?

Input schema has zero parameters, so the baseline is 4. The description adds meaning by explaining that the tool operates on the current page with no required inputs, which is useful context. There are no parameter details to elaborate on.

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

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

Description clearly states the tool runs a WCAG 2.1 AA accessibility audit on the current page using axe-core. It lists specific checks (alt text, form labels, keyboard access, etc.) and distinguishes itself from a fixed checklist, which differentiates it from the sibling alethia_audit_nist.

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 an explicit usage instruction: 'Call after navigating with alethia_tell.' It does not explicitly name alternatives or state when not to use it, but the WCAG-specific scope and context make the appropriate use case clear, especially compared to the NIST audit 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?

Annotations already mark the tool as readOnly, and the description adds valuable behavioral context: it 'does not execute anything', returns compiled IR, per-line confidence scores (0-1), and warnings for unparsed lines. This goes beyond annotations by describing the exact output and failure indication.

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 concise sentences: the first states the core action and non-execution, the second lists the return values, and the third gives use cases. Every sentence earns its place with 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 simple compile-only tool with one parameter and no output schema, the description fully explains purpose, behavior, output format (IR, confidence, warnings), and use cases. It is self-contained and leaves no significant gaps.

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

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

The input schema already fully describes the only parameter (instructions: 'Plain-English instructions to compile (does not execute).') with 100% coverage. The tool description paraphrases this as 'natural-language test instructions' but adds no new semantic detail, so the baseline of 3 applies.

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

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

The description starts with a specific verb 'Compile' and defines the resource as 'natural-language test instructions to Alethia Action IR text'. It also explicitly states 'without executing anything', differentiating it from execution-focused sibling tools like alethia_tell.

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 tells when to use the tool: 'preview what tell() will run, debug coverage gaps, or generate reproducible IR scripts for CI pipelines.' This provides clear use cases and implies it should not be used for actual execution.

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

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

With annotations present (readOnlyHint: false, destructiveHint: false), the description adds meaningful context: it runs in the navigated page rather than the host UI and returns the evaluation result. However, it does not explicitly warn that arbitrary JS may have side effects, though this is partially implied by 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?

Three concise sentences deliver the core purpose, execution context, and usage guidance without redundancy. Information is front-loaded and every sentence earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema) and strong annotations, the description covers purpose, context, examples, and execution environment. It is fully complete for an agent 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?

Schema coverage is 100% and the only parameter 'expression' is well-defined with an example. The description adds usage examples but does not add new parameter-level semantics beyond what the schema already provides, warranting the baseline score.

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

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

The description clearly states the tool evaluates a JavaScript expression in the page under test, using the specific verb 'Evaluate' and identifying the resource. It distinguishes itself from siblings by emphasizing the page context versus the Alethia host UI and positions itself for queries the NLP compiler cannot express.

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

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

Explicitly says 'Use this for queries the NLP compiler cannot express' and provides concrete examples (counting elements, reading computed styles, checking localStorage). It also implicitly excludes use for host UI operations and anything the NLP compiler can handle, giving clear when-to-use and when-not-to-use 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 adds meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations, detailing exactly what the evidence pack contains ('every tool call... timestamps, inputs, outputs, policy decisions, and a SHA-256 integrity hash'). This enriches the agent's understanding of the tool's output and purpose, though it does not specify the exact format or delivery mechanism of the pack.

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

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

The description is three sentences, front-loaded with the primary action, followed by useful detail about contents and usage. Every sentence contributes distinct information without redundancy or fluff, making it appropriately concise and well-structured.

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

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

For a tool with no parameters and no output schema, the description covers the essential aspects: what it does, what it includes, when to use it, and its purpose. The annotations cover safety traits, and the description fills in the behavioral and usage context, achieving a high level of completeness.

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 the input schema is trivially complete. The description adds contextual meaning by explaining what the evidence pack will include, which indirectly clarifies the tool's output, even though param semantics are not directly addressed. This meets the baseline for zero-parameter tools.

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

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

The description clearly states the tool's function: 'Export the full session recording as a signed evidence pack.' It specifies the resource (session recording) and unique output (signed evidence pack with timestamps, inputs, outputs, policy decisions, and SHA-256 hash), distinguishing it from sibling tools like alethia_audit_wcag or alethia_status.

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 explicit guidance on when to use the tool: 'Use at the end of an agent loop to produce cryptographic proof of everything the agent did.' It also contextualizes the use case ('Designed for compliance review and chain-of-custody'), though it does not explicitly mention when not to use it or name alternatives.

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

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

The description adds key behavioral context beyond annotations: the runtime keeps running and continues to accept tool calls, clarifying that this is non-destructive and only affects the UI. This complements the idempotentHint and destructiveHint annotations without 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 concise sentences entirely focused on the action and its scope. No fluff or redundant wording; every word earns its place.

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

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

For a zero-parameter UI-hiding tool, the description is fully complete. It explains what happens to the runtime, which is the one behavioral nuance the agent needs to know. The sibling set (show_cockpit, kill_switch) makes the contrast implicit but sufficient.

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

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

The tool has zero parameters, and schema coverage is effectively 100% (empty schema). The description needs to explain no parameters, and the baseline for zero-param tools is 4. It correctly focuses on the action rather than parameter details.

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 'Hide the Alethia cockpit window' with a specific verb and resource. It distinguishes itself from sibling tools like show_cockpit and activate_kill_switch by clarifying that the runtime continues, making the action's scope explicit.

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

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

The description gives clear context: use this to dismiss the visible window while keeping the runtime operational. It implies the contrast with show_cockpit and non-destructive tools, but does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

The description adds significant behavioral context beyond the annotations: it explains the tool scans for destructive actions, auto-generates an 'EA1 Safety Gate Verification' block, and returns an array of test blocks. This complements the readOnlyHint and destructiveHint annotations with concrete output and scanning behavior. No contradiction exists; the annotations indicate a safe read-only operation and the description confirms it only scans and suggests, not executes.

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

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

The description is three sentences, each earning its place: the first states the main action, the second details the return value and key generated block, and the third gives usage guidance. It is front-loaded with the primary verb and resource, with no irrelevant filler. The structure is clean and efficient.

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

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

For a tool with only one parameter and no output schema, the description is quite complete. It explains what the tool does, what it returns (an array of plain-English test blocks), and gives a concrete example of the safety gate block format. It could have elaborated on error handling or edge cases, but given the simplicity of the tool, the information provided is sufficient.

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

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

The schema description coverage is 100%, so the parameter 'url' is fully documented with value examples (file://, http://localhost). The tool description adds minimal extra parameter meaning; it only explains that the URL is navigated to and scanned, which is implicit in the tool's purpose. Since the schema already provides the necessary details, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: it navigates to a URL, scans for interactive elements, and generates a candidate NLP test suite. It explicitly differentiates from sibling tools by noting the output is 'ready to pass to alethia_tell', making it distinct from the tell, compile, and eval tools. The verb 'generate' paired with the resource 'candidate test suite' is specific and unambiguous.

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

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

The description provides explicit usage context: 'Use this to bootstrap test coverage for a new page or to discover what the safety gate should be watching.' It also indirectly references the alternative tool (alethia_tell) as the downstream consumer of the output. However, it does not include an explicit 'when not to use' statement or direct comparison to alternatives like alethia_compile, so it falls short of a perfect 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that, such as capturing the 'current page' and returning a base64-encoded image, which aligns with and reinforces the read-only nature of the operation.

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: the first states the action and output format, the second provides usage context. It is front-loaded, efficient, and contains 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?

For a tool with no parameters and no output schema, the description fully covers the necessary information: what it does, what it returns, and when to use it. There are no significant gaps given the tool's simplicity.

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

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

The tool has zero parameters, so the baseline of 4 applies. No parameter description is needed, and the schema coverage is trivially 100%.

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

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

The description uses a specific verb and resource: 'Capture a PNG screenshot of the current page' and explicitly states the output format (base64-encoded image). It also distinguishes the tool from siblings by mentioning its role after alethia_tell steps.

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 tells when to use the tool: 'after running test steps with alethia_tell' and why: 'to visually verify what the browser is showing'. It does not explicitly name alternatives, but the context is clear enough for an agent to select it appropriately.

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 idempotent and non-destructive behavior. The description adds valuable context about the server running on a random available port on 127.0.0.1 and clarifies the return value (base URL and list of demo pages). No contradiction exists between description and annotations.

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

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

The description is concise, with three sentences that front-load the core action, then provide usage context, technical detail, and return information. Every sentence serves a purpose with no fluff.

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, simple tool, the description is fully complete. It covers purpose, when to use, how it behaves (random port, loopback), and what it returns, even without an output schema. This is more than sufficient for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately avoids redundant parameter explanations and instead adds value by describing the server's operational details and return 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?

The description clearly states the tool's purpose: 'Start a local HTTP server for the built-in Alethia demo pages and return the base URL.' It uses a specific verb ('start') and resource ('local HTTP server'), and distinguishes itself from siblings by mentioning its role in serving demo pages and its relationship to alethia_tell.

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 tells when to use this tool: 'Use this to serve demo pages on localhost so they appear in preview panels' and 'Call this before alethia_tell to get a localhost URL instead of a file:// path.' This provides clear context and an explicit sequencing instruction relative to a sibling 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the headless-session context and the visual highlight behavior, but doesn't disclose additional side effects or return behavior. It does not contradict 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 two sentences, front-loaded with the core action. The first sentence defines the tool and describes the cockpit's visual elements; the second sentence gives usage guidance. No wasted words.

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

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

For a no-parameter, no-output-schema display tool, the description fully covers what the tool does and when to use it. It is complete within its simple context and complements the sibling tool hide_cockpit.

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 the schema coverage is effectively 100%. No parameter documentation is needed, and the description adds no parameter info, which aligns with the baseline of 4.

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

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

The description clearly states the tool's action: "Show the Alethia cockpit window" – a specific verb and resource. It also explains what the cockpit is (oversight surface with live highlighting) and distinctly contrasts with the sibling tool alethia_hide_cockpit.

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 explicit usage context: "Use this to pop the UI into view during a headless-launched session for demos, review, or partner walkthroughs." It does not name alternatives or specify when not to use, but the context is clear and practical.

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. The description adds value by detailing what the probe returns (runtime version, policy profile, kill switch state, etc.) and clarifies it is an identity/health probe, which is consistent with the annotations and adds useful context for the agent.

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: the first states the purpose and return data, the second gives usage context. It is front-loaded with the most important information, and there is zero waste or repetition.

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?

Since there is no output schema, the description must convey what the tool returns, and it does so thoroughly. It enumerates all key fields and provides operational context (liveness check before tell calls). For a zero-parameter status tool with strong annotations, this is complete.

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

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

The input schema has zero parameters, so there is no parameter documentation burden. The description implicitly reinforces that the tool takes no inputs by framing it as a probe, and the baseline for zero-parameter tools is 4, which is appropriate here.

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

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

The description opens with 'Health and identity probe' and immediately lists the specific return values: runtime version, policy profile, kill switch state, driver statistics, page domain, and capabilities. This clearly distinguishes it from sibling tools like alethia_tell or alethia_compile, which perform actions rather than status checks.

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 explicitly states to use this tool for liveness checks before sending tell() calls and at the start of an agent loop to verify a known-good state. This provides clear context for when to use it relative to siblings, though it does not explicitly name alternative 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?

The description discloses significant behavioral traits beyond the annotations: destructive actions are blocked unconditionally, sensitive input is blocked unless allowSensitiveInput is true, it returns per-step results, policy audit records, and a SHA-256 integrity hash, and mentions ~13 ms per step average performance. These details provide substantial transparency about safety constraints, output, and performance, going well beyond the simple boolean hints.

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

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

The description is concise, four sentences long, and front-loaded with the core purpose. Each sentence provides distinct and valuable information: purpose, outputs, safety constraints, and performance. No redundant or filler content is present.

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

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

The description covers the core function, return values (per-step results, policy audit records, integrity hash), and key constraints (destructive block, sensitive input gate, performance). It also implies a prerequisite (the page currently being driven). However, it lacks a bit of detail on what 'policy audit records' contain or how results are delivered (e.g., output format), which would be useful given the absence of an output schema.

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

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

Schema description coverage is 100%, and each parameter (name, instructions, allowSensitiveInput) has a clear description. The tool description adds no extra parameter semantics beyond the schema; it mentions allowSensitiveInput in behavioral context but does not provide additional syntax, formatting, or usage details that aren't already present in the schema.

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

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

The description clearly states the tool's function with a specific verb ('Execute') and resource ('natural-language E2E test instructions against the page Alethia is currently driving'). However, it does not explicitly distinguish from the sibling tool alethia_tell_parallel, which likely performs a similar action in parallel, so full differentiation is missing.

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 context for when to use it (running natural-language E2E tests) and mentions blocking of destructive actions and sensitive input, which implies careful use with flags like allowSensitiveInput. However, it does not explicitly state when to use this tool over alternatives like alethia_tell_parallel, and no exclusionary or alternative guidance is 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds concrete behavioral details: it spawns a browser instance per spec, runs them in parallel, and returns all results together. It also hints at resource usage by mentioning spawning per spec. 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 two sentences, front-loaded with the core action, followed by execution details and a use case. Every sentence adds value; 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?

For a tool with one well-documented parameter and a clear execution model, the description provides a complete mental model: parallel browser instances, input specs, and aggregated results. It doesn't detail the return format, but no output schema exists and the description gives a reasonable expectation. Given the simplicity, this is nearly complete.

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

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

Schema coverage is 100%, so the schema already defines the specs array with url, instructions, and optional name. The description repeats 'Takes an array of test specs' without adding semantic detail beyond the schema. Baseline 3 applies because the schema carries the param 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 opens with a specific verb+resource: 'Run multiple test flows concurrently — each against a different URL.' It clearly distinguishes from siblings like alethia_tell by emphasizing parallelism and multiple URLs. The purpose is unambiguous and action-oriented.

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 when to use: 'Use this to verify multiple pages simultaneously.' It implies this is for parallel verification across different URLs, which differentiates it from single-flow tools. It does not name alternatives or exclusions, but the usage context is clear.

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