entroly-context-engine

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

The description discloses several behavioral traits: the operation is durable and idempotent, continuation returns a specific status, terminal returns verified output, and no provider call is performed. These details add significant context beyond the absent annotations. However, it does not mention error conditions or required prior state (e.g., session from prepare_proof_guided_context).

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. It could benefit from breaking into sections (e.g., parameters, behavior) but is efficiently written without waste.

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 explains the output types (continuation vs terminal) and idempotency, but it omits critical context such as the need for a session created by 'prepare_proof_guided_context', the format of model_output, and the exact structure of the output schema. Given the complexity and the presence of an output schema, more completeness is expected.

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 bears full responsibility for explaining parameters. It does not mention session_id, model_output, or idempotency_key at all, leaving agents without guidance on what each parameter represents or how to construct 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 'Verify one model round and return exact evidence or a final answer,' which is a specific verb+resource. It explains continuation vs terminal responses, clearly indicating the tool's role in the proof-guided context workflow. However, it does not explicitly distinguish this from sibling tools like 'verify_beliefs' or 'verify_response', leaving some ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'verify_beliefs' or 'verify_response'. The description focuses on behavioral details but omits when to invoke or when not to, leaving an agent without clear selection criteria.

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

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

With no annotations provided, the description carries full burden and discloses that the tool runs 5 named passes over all fragments and returns a detailed HealthReport. However, it does not explicitly state whether the tool is read-only or has side effects, which is a minor gap. The analysis passes and return structure are well-described.

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 fairly long but well-organized with a numbered list of passes and a clear listing of return fields. Every sentence adds value, though it could be slightly more concise. The structure aids readability.

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

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

Given the tool has zero parameters and an output schema exists (implied by context and described in the description), the description is complete. It covers all necessary information: what the tool does, how it works (5 passes), and what it returns (HealthReport fields).

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 fully covered. The description does not need to add parameter details, and it does not. Baseline 4 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 clearly states the tool analyzes codebase health, listing five specific analysis passes. It distinctly identifies the resource (codebase fragments in current session) and the action (health analysis). Among the sibling tools, none perform this exact function, so it is well-differentiated.

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

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

The description explains what the tool does (runs 5 analysis passes) but does not provide explicit guidance on when to use it versus alternatives like scan_for_vulnerabilities or security_scan. There are no use-case exclusions or references to other tools, leaving the agent to infer appropriate usage 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool analyzes beliefs and determines re-verification, invalidation, and risk level. However, it does not state whether it has side effects (e.g., modifying anything) or any other behavioral traits beyond what is described.

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 relatively concise, with the main purpose front-loaded. It uses two paragraphs and a structured args section. Some redundancy (e.g., 'Analyze the blast radius' repeated in first line and second paragraph), but overall 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?

Given that there is an output schema (not shown but present), the description need not explain return values. It covers the inputs, outputs, and process adequately for a single-parameter tool with moderate complexity.

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% coverage, so the description must compensate. It explains that 'changed_files' is a 'Comma-separated list of changed file paths', adding meaning beyond the schema's mere 'string' type. This is adequate for a single-parameter tool.

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

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

The description clearly states the tool's purpose: 'Analyze the blast radius of file changes on existing beliefs.' It specifies the input (list of changed files) and outputs (beliefs needing re-verification, invalidation, risk level), making it distinct from 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 explains the input format and what the tool does, but does not provide explicit guidance on when to use it versus alternatives (e.g., other analysis tools like verify_beliefs). It implies usage when files change, but lacks exclusions or alternative suggestions.

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

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

No annotations exist, so the description carries full responsibility for behavioral disclosure. It only says 'save state plus explicit decisions needed for safe continuation,' but omits side effects, required permissions, or what 'safe continuation' entails.

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?

Extremely concise (6 words), but under-specification sacrifices completeness. The description is too short to convey essential information about parameters or usage.

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 5 undocumented parameters, no annotations, and many sibling tools, the description is severely incomplete. Even with an output schema, the lack of parameter guidance and behavioral context leaves users guessing.

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

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

Schema description coverage is 0%, and the description adds no meaning to any of the 5 parameters. Users cannot infer what values like 'project', 'decisions', or 'current_step' represent.

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 states it saves state and explicit decisions for continuation, providing a general purpose. However, it does not differentiate from sibling tools like 'resume_state' or 'remember_fragment', and lacks a specific verb-resource combination.

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 over alternatives. The sibling list includes many potentially overlapping tools, but no context is provided for choosing among them.

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

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

No annotations are provided, so the description carries the full burden. It outlines the workflow: scanning directories, extracting entities, resolving dependencies, and writing artifacts to the vault. This gives the agent a clear understanding of the tool's behavior and 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 concise and well-structured, with a clear initial statement followed by bullet points for arguments. It avoids unnecessary details while covering essential functionality.

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 complexity of the tool (scanning, extracting, resolving dependencies, writing artifacts), the description covers the main steps and output format (belief artifacts with frontmatter). The presence of an output schema further reduces the need to detail return values. However, it could mention potential limitations or error conditions.

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?

Despite the schema_coverage being 0%, the description includes an explicit 'Args' section that explains both parameters: 'directory: Path to scan. Defaults to the project root.' and 'max_files: Maximum files to process (default: 200).' This adds meaningful context beyond the schema's 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 clearly states the tool's purpose: 'Compile source code into belief artifacts (Truth → Belief pipeline).' It specifies the types of source files, what it extracts, and the output. This is distinct from siblings like compile_docs, which likely handles documentation.

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 lacks explicit guidance on when to use this tool versus alternatives. Although it explains what the tool does, there is no mention of when not to use it or which sibling tools to consider instead. With many related tools, this diminishes usability.

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

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

With no annotations provided, the description carries the full burden. It discloses that beliefs are created with confidence 0.80 and that it processes a default of up to 50 files. However, it does not mention whether the tool overwrites existing beliefs, is idempotent, or any side effects on the vault. Overall good but could be more explicit about behavioral traits.

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 and well-structured: one sentence for the main purpose, followed by a paragraph with additional context and parameter details. No extraneous words or redundancy. Each sentence adds value.

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

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

Given the tool has an output schema and only two parameters, the description provides sufficient context for an agent to understand the tool's function. It explains the input (doc files), the confidence level, and parameter defaults. However, it could be more complete by explaining what 'belief artifacts' are and how they affect the vault state.

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. The description lists the 'directory' and 'max_files' parameters with their defaults and brief explanations (directory defaults to project root, max_files defaults to 50). However, it does not add deeper semantics like acceptable file types, error handling, or how the directory path is resolved. This is minimal added value over the schema 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 clearly states the tool's purpose: 'Compile markdown documentation files into belief artifacts.' It specifies the action (compiling), resource (markdown doc files), and output (belief artifacts with confidence 0.80). It distinguishes from siblings like compile_beliefs by focusing on documentation files only.

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 explains the tool ingests project-level docs like README.md, ARCHITECTURE.md, etc., into the vault. It provides clear context for when to use it (for project documentation), but does not explicitly mention when not to use it or name alternative tools. There is no exclusion or comparison to 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?

No annotations are provided, so the description carries full burden. It implies a read-only scan but does not explicitly state it is non-destructive or safe. It lacks details on permissions or 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 concise and well-structured. The purpose is front-loaded, and each sentence adds value. Only two short paragraphs cover purpose, usage, and parameter.

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

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

For a simple tool with one optional parameter and an output schema (not shown), the description is complete. It covers core behavior, parameter, and usage context. No explanation of return values needed due to 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?

The schema has 0% coverage, but the description adds meaning: 'Path to scan. Defaults to the project root.' It clarifies the default behavior, though it does not specify path format or validation.

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: find source files without belief artifacts in the vault. It specifies supported file types and mentions a related tool (compile_beliefs), distinguishing its role.

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 it is useful before running compile_beliefs, providing clear context. It does not mention when not to use or alternatives, but the sibling list includes many unrelated 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?

With no annotations provided, the description fully bears the burden of disclosure. It states that the tool does not call an LLM, which is key behavioral information. It also explains that 'recoverable=True' persists a recovery bundle, offering transparency about side effects. However, it does not mention potential destructive actions or authorization needs.

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

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

The description is compact (about 100 words), front-loaded with the purpose, and uses bullet points to efficiently present the acceptable formats. Every sentence adds value without 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?

Given the presence of an output schema (which may document return values), the description is adequate for a simple creation tool. However, with over 60 sibling tools, it lacks guidance on when to use this tool versus 'create_context_receipt_from_path', limiting the agent's ability to differentiate.

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 explains 'documents_json' in detail (three formats). The other five parameters ('query', 'chunk_tokens', 'token_budget', 'overlap_tokens', 'recoverable') are left with only their names and default values, lacking semantic meaning. This is insufficient for a tool with 6 parameters.

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

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

The description clearly states 'Create a Context Receipt from supplied documents', specifying the action and resource. It further distinguishes by noting that it does not call an LLM and lists what the receipt records, making it distinct from similar tools like 'create_context_receipt_from_path' which uses paths.

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 detailed guidance on the acceptable formats for 'documents_json' and explains when to set 'recoverable=True'. However, it does not explicitly guide when to use this tool over its sibling 'create_context_receipt_from_path', leaving some ambiguity for the agent.

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

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

With no annotations, the description carries the burden. It states the operation is 'deterministic and local,' which is useful, but lacks details on side effects (e.g., file creation, overwriting), authentication needs, or error handling for missing files. No contradictions with annotations (none provided).

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 brief (three sentences) and front-loaded with the core action. However, it sacrifices parameter explanation for brevity, which is a trade-off but not excessive 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?

Given 5 parameters, no annotations, and an output schema (which documents returns), the description should at least outline parameter purposes and high-level workflow. It fails to do so, leaving the agent underinformed about how to use this tool effectively.

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

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

Schema description coverage is 0%, and the description adds no explanation for any of the 5 parameters (path, query, chunk_tokens, token_budget, overlap_tokens). The agent gains no semantic insight into their roles or defaults beyond the schema structure.

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: 'Create a Context Receipt from a local document file or directory.' It specifies supported file formats (.md, .txt, .rst) and notes that the result is deterministic and local. This distinguishes it from sibling tools like 'create_context_receipt' (likely for other sources).

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

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

The description implies usage for local text documents but does not explicitly provide when to use this tool versus alternatives (e.g., create_context_receipt) or when not to use it. No prerequisites or exclusions are mentioned.

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

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

No annotations are provided, so the description carries the full burden. It details the files created (SKILL.md, tool.py, etc.) and the structure, which is good. However, it does not disclose potential side effects like overwriting existing skills, required permissions, or whether the operation is reversible.

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 well-organized with a clear intent statement followed by an args section. It is reasonably concise, though the 'Args' block could be tighter integrated into the main prose.

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 lack of annotations and presence of an output schema (not shown), the description provides sufficient context about the tool's purpose and generated artifacts. It could be more complete with details on return value format and conflict handling.

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?

Despite 0% schema description coverage, the tool's description explicitly lists and describes all three parameters (entity_key, failing_queries, intent) with meaningful context, adding value beyond the nullable 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 creates a new skill from a capability gap (Evolution layer), with a specific verb and resource. It distinguishes itself from siblings like 'manage_skills' by focusing on generation from repeated failures.

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 specifies when to use the tool: when the system repeatedly fails on a topic. It implies a trigger condition but does not explicitly exclude other scenarios or mention alternatives like updating an existing skill.

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

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

No annotations are provided, so the description carries the full burden. It fully discloses behavior: each mode's actions, profile tuning, accuracy caveats (non-zero false positives/negatives), and the detailed return structure. This is exceptionally transparent.

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 detailed but well-structured with sections for modes, profiles, returns, and caveats. It is front-loaded with the core purpose. While it is long, every sentence adds necessary information, justifying the 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?

Given the tool's complexity, the description covers all aspects: behavior, parameters, modes, profiles, return values (even including example fields like hallucination_rate and certificates), and caveats. No output schema is provided, but the description makes the result structure clear.

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 fully explains all four parameters: context, output, profile, and mode. It provides meanings, defaults, and allowed values (e.g., mode options, profile list), adding significant value beyond 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 verifies LLM responses and optionally rewrites hallucinated claims. It distinguishes itself from siblings like verify_response and eicv_verify_claim by highlighting it is fully local with no neural model or LLM calls. The specific modes and profiles further clarify the 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 explicit guidance on when to use each mode (audit, annotate, strict) and profile (rag, qa, etc.). It recommends audit-mode for compliance-sensitive applications. However, it does not explicitly mention when NOT to use this tool or directly compare to sibling tools like eicv_verify_claim.

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

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

With no annotations, the description fully discloses that the tool runs locally without neural models or LLM calls, and explicitly warns about non-zero false positive/negative rates, which is critical for trust.

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 well-structured, front-loading the purpose and output, then method and limitations, then args. It is slightly verbose but every sentence adds value.

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 an output schema exists, the description still lists output fields. It covers input, output, method, limitations, and usage contexts, making it complete for this tool's complexity.

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, but the description's Args section provides clear meaning: evidence is grounding context, claim is the single claim, profile selects the abstain band. This compensates fully.

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 it verifies a single claim against evidence using the EICV pipeline, and details the structured output. It distinguishes from siblings like verify_beliefs by specifying the pipeline and output format.

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

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

The description implies usage for factual claim verification with evidence and lists profile options for different contexts. However, it does not explicitly state when to use this tool over alternatives 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?

No annotations are provided, so the description carries the full burden. It explicitly states it pulls from actual engine state (not synthetic) and lists the types of data shown. It does not disclose potential side effects or performance impact, but given it's a read-only dashboard, this is acceptable. The transparency is good but could be more detailed about real-time behavior.

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

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

The description is structured with a clear opening sentence and a bullet list summarizing key metrics. It is front-loaded with the purpose. However, the enthusiastic tone and exclamation marks are slightly verbose for a technical tool description, but the information density is good.

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 zero parameters and an existing output schema (not shown), the description provides a complete overview of what the tool does and the categories of data returned. An AI agent can confidently decide when to call this tool 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?

There are no parameters, so the baseline score is 4. The description adds no parameter information because none is needed. The schema coverage is 100% (empty properties), so the description is not required to compensate.

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 shows live value metrics from engine state, with a list of specific categories. However, the verb 'Show' is somewhat generic, and it could more explicitly state it retrieves a dashboard. It distinguishes from siblings like `get_stats` by focusing on session-specific value metrics, but doesn't explicitly contrast.

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

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

The description says 'Call this anytime,' implying it can be used freely, but it does not provide when-not-to-use guidance or compare to alternative tools like `get_stats` or `explain_context`. The usage context is implied but not explicitly differentiated.

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

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

With no annotations provided, the description carries the full burden. It explains lazy resolution for source paths and the listing behavior with no argument. It does not disclose potential errors or side effects, but the behavior is reasonable for a retrieval tool.

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

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

The description is concise with a clear first line and structured argument explanation. It contains no redundant information, though it could be slightly more streamlined by removing the 'Args:' header effect.

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 presence of an output schema, the description need not explain return values. It covers the main use cases and parameter details. Missing edge cases like invalid handles or error conditions, but overall adequate for a simple 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?

Parameter schema coverage is 0%, so the description must compensate. It does so by explaining 'source_or_handle' as a source path or content-addressed handle, and notes the default is empty. This adds significant meaning beyond the schema's title and type.

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 retrieves exact source content omitted by compressed context, with specific use cases (handle, source path, listing). The verb 'retrieve' matches the tool name, and it is distinct from sibling tools like 'recover_receipt_omission' or 'explain_receipt_omission'.

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 explains when to use the tool (to recover omitted content) and provides three distinct modes of operation. However, it does not explicitly contrast with sibling tools or state when not to use it, which would improve 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?

No annotations are provided, so the description carries full burden. It describes the tool's internal logic (inspecting signals and selecting flows) but does not disclose output format, side effects, or constraints (e.g., rate limits, error handling). The mention that 'Existing tools work exactly as before' subtly reassures non-destructiveness.

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

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

The description is well-structured with clear sections, bullet points for the 5 flows, and a concise instruction to call before optimize_context. It is appropriately sized for the complexity of the tool.

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

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

Given the tool's complexity and lack of annotations, the description provides a thorough overview of the flows and usage context. It does not detail the 4 signals or output format, but the presence of an output schema (not shown) reduces the burden. Overall, it is adequate for agent 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?

Schema description coverage is 0%, but the description includes an 'Args' section explaining each parameter beyond the schema. It defines query as 'user query or event description', explains is_event as indicator for change-driven events, and lists examples for event_type, adding meaningful semantic context.

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 routes a query through the Epistemic Ingress Controller, inspects 4 signals, and selects one of 5 canonical flows. It distinguishes itself from the sibling tool optimize_context by instructing to call this tool before that one.

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 recommends calling this tool before optimize_context, providing clear context. However, it does not specify when not to use it or provide alternative tools for similar purposes, though the sibling list is extensive.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It describes the internal routing and pipeline steps but does not mention side effects, mutability, authentication requirements, rate limits, or any consequences of execution. The term 'execute' implies action, but safety or resource implications are absent.

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 well-organized with a concise opening, a bulleted list of flows, and a separate argument section. Every sentence is informative; no redundancy or filler. It is front-loaded with the core purpose.

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

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

Despite the complexity of executing a multi-step epistemic flow, the description covers the pipeline logic and argument semantics. An output schema exists, so return value explanation is not needed. However, it lacks any mention of error conditions or prerequisites (e.g., required workspace state).

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 supplies all parameter meanings. It clearly defines 'query' as user query/event, 'diff_text' as raw diff for change-driven flows, 'is_event' for change-driven flag, and 'event_type' with examples. This adds full value beyond the empty 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 executes a full canonical epistemic flow end-to-end, listing the specific pipeline steps and their triggers. This distinguishes it from sibling tools like epistemic_route, which is likely just the routing 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 explains the five flow types (Fast Answer, Verify Before Answer, etc.) and their triggering conditions through the Epistemic Ingress Controller, providing context on when each path is used. However, it does not explicitly state when not to use this tool or mention alternatives from the sibling list.

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

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

Despite no annotations, the description fully discloses what the tool shows: per-fragment scoring breakdowns with all dimensions, context sufficiency, and exploration swaps. It implies read-only behavior, but could explicitly state it doesn't modify state.

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

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

Three efficient sentences: purpose, then list of outputs, then usage instruction. No wasted words; front-loaded with key purpose.

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

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

With no parameters and an output schema (not shown but indicated as present), the description sufficiently covers purpose, what is shown, and when to call. Complete for a simple inspection tool.

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

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

The tool has zero parameters, so schema coverage is 100% by default. The description adds no parameter info, but baseline is 4 given no parameters need explanation.

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 explains inclusion/exclusion decisions from the last optimization, using specific verb 'explain' and resource 'context selection decisions'. It distinguishes itself from sibling tools like optimize_context and inspect_proof_guided_context.

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 'Call this after optimize_context to understand selection decisions', providing clear usage context. While it doesn't specify when not to use, the guidance is strong and contextually 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?

No annotations are provided, and the description does not disclose behavioral traits like whether it is read-only, requires authentication, or has side effects. The word 'explain' implies a non-destructive operation, but this is not explicit.

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 very concise (one sentence), but it sacrifices necessary detail. It is front-loaded but incomplete, earning a middle score.

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

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

Given the tool has a defined output schema but the description does not mention it or hint at the explanation's format, the agent lacks contextual completeness to use the tool effectively.

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

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

Schema description coverage is 0%, and the description adds no meaning to the parameters 'receipt_json' and 'chunk_id'. It does not explain their format, constraints, or purpose beyond their names.

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

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

The description clearly states the tool explains why a chunk was omitted from a Context Receipt, distinguishing it from siblings like 'explain_context' and 'recover_receipt_omission'.

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 versus alternatives, such as 'explain_context' or when not to use it. Lacks prerequisites or 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?

No annotations are provided, so the description carries the full burden. It discloses filtering behavior, quality-weighted sampling via PRISM scores, and output format (OpenAI-compatible JSONL). It does not mention any side effects, auth requirements, or rate limits, which is acceptable for an export tool.

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

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

The description is concise with three purposeful sentences plus an Args block. No unnecessary words; every sentence provides essential information.

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

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

Given the presence of an output schema, the description adequately explains the output format and content. It covers filtering criteria, quality sampling, and parameter defaults, making it complete for an agent to 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?

Schema coverage is 0% but the description includes an Args section that explains both parameters (output_path and format) with defaults and notes that only 'jsonl' is currently supported, adding value beyond the schema properties.

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 action (export), resource (vault beliefs), format (JSONL), and purpose (LLM finetuning). It distinguishes itself from sibling tools that read or query beliefs by specifying the export and training data generation function.

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

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

The description provides clear context on when to use this tool: for generating instruction-following pairs from beliefs for fine-tuning. It mentions filtering criteria (confidence >=0.5, non-stale) but does not explicitly exclude other tools or state when not to use it.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It only lists the types of statistics shown but does not reveal whether the tool is read-only, requires authentication, has performance implications, or causes side effects. For a retrieval tool, this is minimal transparency.

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 (two lines plus a bullet list) and front-loaded with the core purpose. Every sentence serves a purpose, though the bullet list could be formatted more cleanly. Overall, it is efficient and to the point.

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 types of statistics returned, which is helpful given the output schema exists. However, it lacks usage guidance and behavioral context. Considering the tool's moderate complexity (no parameters, extensive output) and absence of annotations, the description is adequate but not comprehensive.

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 schema description coverage is 100%. The description does not need to add parameter information; it implicitly confirms that no arguments are required. This is appropriate given the schema, earning a baseline score 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 purpose with a specific verb ('Get') and resource ('comprehensive session statistics'). It lists what statistics are included (token savings, duplicate detection, etc.), making the function clear. However, it does not differentiate from sibling tools like 'entroly_dashboard' or 'checkpoint_state' which might also provide statistics.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it fits with sibling tools. The agent must infer usage context from the description alone, which is insufficient for informed 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?

With no annotations provided, the description carries the full burden. It explains the conversion to a structured fragment, storage, and retrieval via other tools. It does not mention side effects or limitations but is sufficiently transparent.

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 and well-structured: a summary paragraph followed by a clear argument list. Every sentence adds value, and the format aids readability.

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 explains the conversion, storage, and retrieval process. It references the output format as 'same as remember_fragment', and since an output schema exists (per context signals), the description does not need to detail return values. It is adequately 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 0%, so the description provides essential meaning. It defines each parameter: 'diagram_text' as source text, 'source' as identifier, and 'diagram_type' with enum values. This fully compensates for the schema's lack of 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 clearly states the tool's action: 'Ingest an architecture or flow diagram into the context memory.' It specifies the input formats (Mermaid, PlantUML, etc.) and distinguishes itself from sibling tools like 'remember_fragment' by focusing on diagram conversion.

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

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

The description implies usage for diagrams that need structured representation, but does not explicitly state when not to use it or compare with alternatives like 'remember_fragment'. However, the context is clear enough for an agent to determine appropriate use.

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

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

No annotations provided, so the description must fully disclose behavior. It states the tool converts a diff into a structured summary and returns JSON. However, it does not clarify whether the ingested data is stored, the persistence of changes, or any side effects (e.g., modifications to context memory). More details on authorization or error handling would improve transparency.

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 two paragraphs and a bullet list. It is front-loaded with the primary action and quickly details the conversion process. However, the bullet-listed output fields could be slightly more compact, and there is minor redundancy in the first paragraph explaining the same concept.

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 purpose, parameters, and return value sufficiently. An output schema exists (implied by the return fields listed), so repeating those fields is acceptable. However, it lacks information on error handling, input validation, or performance implications, but overall it provides a complete understanding for an AI agent.

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?

Despite 0% schema description coverage, the description adds significant meaning to all three parameters. It explains 'diff_text' as 'raw unified diff text (git diff output)', 'source' with an example, and 'commit_message' as optional for better intent classification. This goes beyond what the schema's titles provide.

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 that the tool ingests a diff, converts it to a structured change summary, and provides intent classification. It uses specific verbs and resources ('ingest', 'diff', 'context memory'). It distinguishes from sibling tools like 'ingest_diagram' and 'ingest_voice' by focusing on code diffs.

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 mentions it is 'particularly useful for understanding recent changes and their architectural impact,' but does not explicitly state when to use this tool vs alternatives or provide exclusions. It lacks guidance on when not to use it or when to use siblings like 'process_change' or 'sync_workspace_changes'.

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

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

With no annotations, the description must fully disclose behavior. It explains the conversion process and output structure, but does not mention side effects (e.g., whether data is persisted) or auth requirements. It implies storage in context memory but lacks explicit mutation semantics.

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 well-structured with a summary line, detailed explanation, explicit argument list, and return value description. It is concise with no redundant content, effectively communicating the tool's purpose and usage.

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 two simple parameters and a clear output schema described. The description covers input, transformation, and output. It mentions the types of extracted information (decisions, actions, etc.) and return structure. However, it does not address error conditions or limitations.

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 description adds substantial meaning to both parameters. For 'transcript', it specifies it is the full transcript text; for 'source', it provides an example identifier. Since the schema has no descriptions, this compensation is crucial and effectively clarifies each parameter's role.

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: 'Ingest a voice/meeting transcript into the context memory.' It specifies the input type and the output structure, making it distinct from sibling ingest tools like ingest_diagram and ingest_diff. The verb 'ingest' and resource 'voice/meeting transcript' are specific.

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 does not provide explicit guidance on when to use this tool versus alternatives. While its purpose implies usage for voice/meeting transcripts, it does not mention exclusions or compare with sibling tools like remember_fragment or ingest_diff, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states 'without advancing it', indicating no state change. It implies a read-only inspection. However, it does not mention auth requirements, idempotence, or other side effects. The key behavioral trait is disclosed, but more detail could improve transparency.

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

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

The description is a single short sentence that is concise and front-loaded. Every word adds value: it identifies the action, the resource, and the key constraint ('without advancing'). No unnecessary words.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers the core action and constraint. However, it does not explain the role of session_id or how to obtain it. The tool is part of a proof-guided workflow, and while the description is mostly complete, a brief mention of the session_id parameter would improve 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?

The input schema has one required parameter session_id, but schema description coverage is 0% (no description in schema). The tool description does not mention session_id or add any meaning beyond the schema. With low coverage, the description should compensate, but it fails to do so.

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

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

The description clearly states the tool inspects the last durable proof-guided response without advancing it. It uses a specific verb ('inspect') and resource ('proof-guided context response'), and distinguishes from sibling tools like 'advance_proof_guided_context' by explicitly noting 'without advancing it'.

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

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

The description implies when to use this tool: to inspect the last response without progressing the workflow. However, it does not explicitly state when not to use or mention alternatives beyond the contrast with advancing. The context of sibling tools ('prepare', 'advance') provides clear context, but explicit exclusions are missing.

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

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

No annotations are provided, so the description carries full burden. It discloses that benchmark runs test cases and computes fitness, and promote/prune uses thresholds. However, it doesn't state whether prune is destructive or if list requires parameters.

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, structured with a summary, bulleted actions, and args list. Every sentence is informative 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?

Given no annotations and an output schema, the description covers all three actions, their conditions, and parameter requirements. It is complete enough for an agent to 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?

Schema description coverage is 0%, but the description fully compensates by explaining the action enum values and indicating that skill_id is required for benchmark/promote actions, which is not evident from 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 it manages the CogOps skill lifecycle with three specific actions (list, benchmark, promote), providing a verb+resource combination that distinguishes it from sibling tools like create_skill.

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 explains when to use each action (e.g., promote when fitness >= 0.7, prune when <= 0.3). While it doesn't explicitly contrast with alternatives, the action definitions give clear usage 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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals the underlying algorithm (0/1 Knapsack), scoring dimensions (recency, frequency, semantic similarity, density), the query refinement side effect, and output ordering rationale. This is far beyond what annotations or schema could convey.

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 well-structured with clear sections for query refinement, output ordering, and argument semantics. Every sentence adds information—algorithm details, scoring dimensions, and practical guidance. Though longer than one sentence, it is information-dense and free of padding.

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 having an output schema, the description enriches the context by explaining the output ordering, the query_refinement.refined_query field, and the algorithmic rationale. For a tool with moderate complexity, it covers purpose, behavior, input semantics, and usage context comprehensively.

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 fully explains both parameters: token_budget as maximum tokens with a default of 128K, and query as the current query/task that can be vague and is expanded by query refinement. This adds meaningful semantics beyond the bare schema fields.

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

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

The description opens with a specific verb and resource: 'Select a high-value context subset for a token budget.' It clearly states what the tool does and distinguishes it from sibling tools by positioning it as 'the core tool' for context selection, with a unique knapsack-based optimization approach.

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 guidance: 'This is the core tool — call it before sending context to the LLM.' It also explains query refinement behavior and when vague queries are acceptable. However, it does not explicitly mention when to avoid this tool or name alternatives, 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?

No annotations provided, so the description carries full burden. It discloses the use of static analysis on imports, callees, test files, and learned patterns, but does not describe side effects, idempotency, or state changes from pre-loading. Adequate but not fully transparent.

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: one sentence for purpose, one for methods, then an Args list. It is front-loaded and every sentence adds value. No wasted words.

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

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

Given the tool's complexity and lacking annotations, the description explains purpose and parameters well. It does not mention output format, but an output schema exists to cover that. It could mention prerequisites or limitations, but overall it is fairly 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 description adds substantial meaning to each parameter: file_path is 'the file currently being accessed', source_content is 'the source code content (for static analysis)', language is 'Programming language (python, typescript, rust)'. This goes far beyond the bare schema, which has low 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 clearly states the tool's purpose: predict and pre-load context needed next. It explains the methods (static analysis + learned patterns). However, it does not explicitly differentiate from sibling tools like recall_relevant or smart_read, which also deal with context retrieval, so it's not 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?

The description gives context on when to use (when you want to pre-load likely needed context) but does not specify when not to use or mention alternatives. It lacks explicit guidelines for selection among 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?

With no annotations, the description carries the burden. It discloses that the tool performs only local operations (selection, security checks, commitments, auditing) and does not call a model. It also mentions the path constraint. This is reasonably transparent, though it lacks details on error handling or permissions.

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 multiple sentences that front-load the purpose and then detail what the tool does. No superfluous information 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?

Given the tool has 7 parameters and no param descriptions, the description is incomplete for parameter guidance. It does provide a clear workflow and output usage, but the lack of param semantics leaves a significant gap. The presence of an output schema reduces the need to describe return values, but parameter guidance remains lacking.

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%, but the description does not explain any parameters beyond implying path must be inside the project root. The other 6 parameters (query, max_rounds, token_budget, idempotency_key, max_chunks_per_round, recovery_token_budget) are left completely undescribed, failing to add meaningful 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 clearly states the tool's purpose: 'Prepare a durable proof-guided model request from local documents.' It specifies what the tool does (local selection, security checks, commitments, signed auditing) and distinguishes it from siblings by noting it does not call a model, and directs the next step to 'advance_proof_guided_context'.

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 a clear workflow: use this tool, then send the returned request to the host's model route, then pass the model text to 'advance_proof_guided_context'. It also states the path constraint. However, it does not explicitly mention when not to use this tool or list alternatives, but the context is sufficient.

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

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

Without annotations, the description discloses several behavioral traits: it modifies SKILL.md and receipt.json only when persist=true, never modifies AGENTS.md or CLAUDE.md, performs prompt-injection scanning, and notes that recalled text is evidence not authority. This goes beyond basic expectations.

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 starts with a clear purpose statement and uses a structured Args list. Each sentence adds value, though the paragraph could be slightly more concise. Overall efficient and well-organized.

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

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

Given the tool's complexity, absence of annotations, and presence of an output schema, the description adequately explains purpose, parameters, side effects, and safety. It covers what is needed for an agent to use 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 description adds significant meaning to all four parameters beyond the input schema. For example, task is 'the concrete task', agent_id is 'MemoryOS identity used for scoped recall', token_budget specifies range 256-8000, and persist explains file writes. Schema coverage is 0%, so the description fully compensates.

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 prepares an expiring, receipt-backed task skill before agent work. It explains the capsule combines memory and recall, distinguishing it from siblings like recall_relevant or vault_write_action, though it does not explicitly contrast them.

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

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

The description indicates use 'before agent work' and explains the tool is for preparation, but does not explicitly state when not to use it or provide alternatives. Some guidance is given but not comprehensive.

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

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

No annotations are provided, so the description carries the full burden. It transparently describes processing a diff, intent classification, code review, belief impact, and output of a PR brief.

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, well-structured with bullet points for pipeline steps and an Args section, front-loading the main purpose.

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

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

The tool has an output schema (implied), and the description mentions the output is a structured PR brief. With clear parameter explanations, it is sufficiently 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?

Despite 0% schema description coverage, the description lists the three parameters with explanatory text, adding meaning beyond the schema's names and types.

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

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

The description clearly states it processes a code change through the Change-Driven pipeline (Flow ④), listing the pipeline steps and distinguishing it from 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 explains what the tool does but does not explicitly state when to use it versus alternatives 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?

Discloses key behavioral traits: default slim pointer list, BM25 plus feedback loop, result size cap, and reasoning for default view. No annotations exist, so description carries full burden, which it handles well.

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?

Well-structured with summary first, then details. Each sentence serves a purpose—explaining algorithm, default behavior, parameter guidance. Could be slightly tighter but effective.

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 an output schema exists, the description appropriately omits return value details but covers default slim output and full option. Addresses result size limitation. Missing edge cases like empty query but overall complete for the tool's purpose.

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?

Adds meaning beyond schema: explains the 'full' parameter effect, default value, and the rationale (overflow cap). Query and top_k are mentioned but less detailed; still adds value over bare schema names.

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

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

The description clearly states it performs semantic recall of stored fragments, mentioning BM25 ranking and feedback loops. It distinguishes its default slim output from the full option, but does not explicitly differentiate from similar sibling tools like vault_search or entroly_retrieve.

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?

Provides clear guidance on when to use the full parameter, explaining the result size limitation and recommending against it unless full text is needed. However, no explicit when-not-to-use or alternatives 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?

No annotations are provided, so the description must bear the burden of behavioral disclosure. It mentions recording a status but fails to disclose whether the operation is idempotent, what happens on duplicate request_id, or if it overwrites previous results.

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

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

The description is concise with a clear main sentence and an 'Args' block. The strong signal context adds some value but is slightly extraneous. Overall, it is well-structured 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?

The description explains input parameters well but does not cover output, error handling, or edge cases (e.g., invalid request_id). Given the presence of an output schema, the lack of output explanation is acceptable, but the tool's behavior in unusual scenarios is not addressed.

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 description includes an 'Args' section that explains each parameter's meaning (e.g., request_id as trace_id, passed as CI green, pipeline examples). This adds substantial value beyond the input schema, especially given 0% schema description 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 clearly states it records CI pipeline pass/fail status. The verb 'Record' and resource 'CI pipeline...status' are specific. However, it does not explicitly differentiate from sibling tools like record_test_result, which could cause confusion.

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

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

The description implies usage when a CI result is available and notes it's a strong signal. However, it does not explicitly state when not to use it or mention alternative tools for similar outcomes (e.g., test results).

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

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

With no annotations, the description fully explains the meaning of exit codes (0=success, non-zero=failure) and emphasizes that it is a strong signal. It does not cover side effects or permissions, but for this simple tool it suffices.

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 well-structured with a clear purpose, a note about strong signal, convention explanation, and an args list. Every sentence adds value, no redundant information.

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

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

For a simple tool with 3 parameters and no annotations, the description covers purpose, parameter semantics, and conventions completely. Output schema exists but its explanation is unnecessary. The description is self-contained and 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?

Despite 0% schema description coverage, the description thoroughly explains each parameter: request_id is the trace_id from optimize_context, exit_code is the subprocess exit code, and command is an optional representation. This adds significant value beyond 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 verb 'record' and the resource 'exit code of a command', distinguishing it from sibling tools like record_ci_result and record_test_result. It 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 explains that this is for a real subprocess exit code, providing context on when to use it. However, it does not explicitly exclude situations or mention alternatives, though sibling names imply differentiation.

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

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

No annotations provided, so description carries full burden. Describes the action as recording an outcome with specific parameters. Discloses the possible outcome values. No hidden side effects mentioned, but it's a simple logging action.

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?

Very concise: one line for purpose, one line for signal strength, then bullet-like args. No unnecessary words, well-structured.

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

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

Given the presence of siblings like 'record_outcome', this description clearly specializes. It includes args and context about signal strength. An output schema exists, so return values are covered externally. Slightly could add more about when to prefer this over 'record_outcome'.

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?

Adds meaning beyond schema: explains that 'request_id' corresponds to trace_id from optimize_context, lists the three possible values for 'outcome' (schema has 0% enum coverage), and clarifies 'files_modified' as number of files touched.

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?

Clear verb 'record' and specific resource 'whether the user accepted, reverted, or retried an AI edit'. Distinguishes from generic 'record_outcome' sibling by specifying it's about AI edits.

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?

States that this is a strong signal of user behavior indicating code success, implying when to use. Does not explicitly say when not to, but provides clear context compared to siblings like 'record_outcome'.

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

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

With no annotations provided, the description fully discloses behavioral traits: it feeds the RL loop, the success flag is recorded as an agent_self_report event with strength=weak and include_in_default_training=False, and default labeling rules ignore it. This goes beyond basic functionality.

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 well-structured with a clear opening sentence, a paragraph explaining the RL purpose, an Args section, and a NOTE. Every sentence adds unique value, and there is no unnecessary 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?

Given the tool's complexity (2 parameters, no annotations, existing output schema), the description covers purpose, usage, behavioral details, and parameter semantics thoroughly. It distinguishes from siblings and provides actionable guidance.

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 description includes an explicit Args section that explains both parameters: fragment_ids (comma-separated IDs) and success (boolean, default true). This adds meaning beyond the input schema's type and requirement, especially given the 0% schema description 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 clearly states the tool's verb 'record' and resource 'outcome', explicitly stating it feeds the reinforcement learning loop. It distinguishes itself from sibling tools like record_test_result, record_command_exit, and record_ci_result, which are mentioned as alternatives for honest signals.

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 (for recording fragment outcomes for RL) and when not to (for honest training signals, use record_test_result etc.). It names specific alternatives and explains that default labeling rules ignore this tool's signal.

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

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

No annotations provided, so description carries full burden. It does not disclose behavioral traits like idempotency, side effects, or error conditions. Merely stating 'Record' gives minimal transparency for a write 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?

Concise introductory sentence followed by structured Args section. No wasted words, though the Args could be slightly more compact. Good front-loading of purpose.

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

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

Covers input parameters well but lacks description of return value or side effects. With an output schema present and no annotation, the definition would benefit from explaining what the tool returns or confirms.

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%, but the description's Args section adds meaningful semantics (e.g., request_id is 'trace_id from optimize_context', passed is boolean, suite/detials are optional). Adequately compensates for lack of schema info.

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 it records test run outcomes (pass/fail) and explicitly distinguishes from sibling 'record_outcome' by noting this is a 'strong signal' from actual test execution, not agent self-report.

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 advises to call 'when actual test execution produced a real pass/fail outcome' and contrasts with 'record_outcome', providing 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?

Despite no annotations, the description discloses key behavioral traits: the recovery bundle is read from the local store, and results carry 'verified=true' only when provably identical via fingerprint and storage-integrity hash. It does not mention permissions, rate limits, or any side effects, but covers the verification mechanism and storage source.

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 and well-structured: it starts with the main purpose, then explains conditions, usage options, and the verification guarantee. Every sentence adds value, and the length is appropriate for the complexity.

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 presence of an output schema (not shown but indicated), the description covers parameters, usage conditions, and return behavior adequately. It lacks details on error scenarios or what happens with invalid receipts, but overall provides sufficient context for a recovery tool with moderate complexity.

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 adds meaning for 'chunk_id' (optional, used for partial recovery) and implies 'receipt_json' is the receipt to recover from. However, it does not elaborate on the format or constraints of 'receipt_json', leaving some ambiguity. The description compensates partially but could be more detailed.

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 it recovers full text omitted by a Context Receipt, using a specific verb 'Recover' and object 'omitted text'. It distinguishes from sibling 'explain_receipt_omission' by emphasizing it returns the exact content byte-for-byte, not just an explanation.

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

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

The description provides clear conditions for use: works only on receipts created with 'recoverable=True', and offers guidance on partial recovery via 'chunk_id'. However, it does not explicitly mention when not to use this tool or suggest alternatives beyond the implicit contrast with 'explain_receipt_omission'.

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

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

With no annotations provided, the description carries the full burden. It discloses the key behavior: marking beliefs as stale (a mutation) and identifies that it does not recompile but triggers later recompilation via 'verify_beliefs'. The side effect (status change) is clear. No contradictions.

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 a summary line and an Args section. It avoids unnecessary words. However, the first line and Args section slightly overlap in stating 'changed files'. Still, it is well-structured and easy 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?

Given the tool's simplicity (one parameter, output schema exists), the description covers all necessary context: what it does, when to use it, the input format, and the follow-up step. The output schema handles return value transparency, so no further explanation is needed.

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

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

The single parameter 'changed_files' is described as 'Comma-separated list of changed file paths', which adds crucial semantic meaning beyond the schema's generic 'string' type. The description also explains how it is used ('finds related beliefs'), making the parameter's purpose very clear.

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 ('mark beliefs as stale') and resource ('beliefs'), and includes context ('after file changes') and a flow reference (Flow ④ doc-refresh). It clearly distinguishes from siblings like 'verify_beliefs' which is mentioned as the next 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 tells when to use the tool ('after file changes') and describes its role in a workflow ('so the next verify_beliefs pass...'). However, it does not explicitly state when not to use it or mention alternative tools, though the context implies it is part of a specific flow.

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 without annotations, the description discloses key behavioral traits: dedup via SimHash, entropy scoring, automatic merging of duplicates with salience boosting, and pinned behavior. It does not mention permissions or side effects, but covers the core algorithmic behavior.

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

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

The description is structured with a brief main sentence followed by technical details and parameter list. It is informative without being overly verbose, though it could be tightened slightly.

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 parameter details and core behavior, but given the complexity and many sibling tools, it lacks context about where this tool fits in the broader ecosystem. It does not address output schema or return values, but that is acceptable since an output schema is present.

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%, but the description adds meaningful explanations for each parameter: content text, source origin, token count auto-estimation, and pinned behavior details. This compensates for the lack of schema descriptions.

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

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

The description clearly states the tool stores a context fragment with automatic dedup and entropy scoring. It uses specific verbs and describes the resource ('context fragment'). However, it does not explicitly distinguish from sibling tools like vault_write_belief, which might have overlapping 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 does not provide guidance on when to use this tool versus alternatives. It fails to specify when not to use it or identify prerequisites. For a tool with many siblings, this is a significant omission.

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

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

No annotations provided, so description carries full burden. It states the transformation but omits details on input validation, error handling, or output structure. Adequate but minimal.

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?

Single sentence, efficient and front-loaded. No fluff, but could benefit from slight expansion on input expectations.

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?

Simple tool with one param and output schema; description covers basic purpose. Lacks detail on expected input structure, but sufficient for a straightforward rendering task.

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 description does not add meaning beyond the param name 'receipt_json'. The role is implied but no specifics on format or structure required.

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 uses specific verb 'Render' and resource 'Context Receipt JSON artifact' to produce 'Markdown report'. This clearly states the tool's function and distinguishes it from siblings like create_context_receipt or explain_context.

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 versus alternatives like explain_context or create_context_receipt. Lacks explicit context for 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?

No annotations are provided, so the description carries the full burden. It indicates a read operation ('Return') but does not disclose any side effects, authentication needs, or limitations. The description is adequate but lacks depth.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence adds essential information. No fluff, perfectly 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?

The tool has an output schema (as per context signals), so return values are documented elsewhere. The description provides enough context (repos, ownership, formats) for a simple one-parameter tool. It could mention the output structure briefly, but given the output schema, it's sufficiently 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 one parameter (format) with no description (0% coverage). The description adds value by specifying 'Supported formats: markdown, json,' which clarifies valid values beyond the schema. This compensates well for the lack of schema descriptions.

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

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

The description clearly states the tool returns the canonical Entroly file map across specific repos (Python, Rust core, WASM) and explains its use for understanding ownership boundaries. The verb 'return' and resource 'file map' are specific and distinct from sibling 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 explicitly says 'Use this to understand ownership boundaries and where logic currently lives,' providing clear context. However, it does not specify when not to use it or mention alternatives among the many siblings, which would elevate it to 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?

With no annotations, the description must disclose behavioral traits. It mentions the resume action and a special case for query omission, but does not describe side effects, permissions, or output characteristics. The presence of an output schema is not leveraged in the description.

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 very short (11 words) and front-loaded, but it sacrifices necessary detail for brevity. It is not verbose, but the conciseness comes at the cost of clarity and completeness.

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

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

Given the tool has 2 parameters, an output schema, and many sibling tools, the description is insufficient. It lacks details on parameter interactions, return value, and when to use this tool over others, leaving significant gaps for the agent.

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. The description vaguely references 'query' but does not explain the meaning or usage of 'query' or 'project'. No parameter details beyond the tool-level hint are provided.

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 'Resume' and identifies the resource 'state', and hints at a unique behavior ('omit query only for latest-checkpoint'). However, it does not explicitly distinguish from siblings like 'checkpoint_state' or 'recall_relevant', which could also involve resuming.

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?

Only a single condition is provided ('omit query only for latest-checkpoint behavior'), without any when-to-use or when-not-to-use guidance compared to sibling tools. No explicit alternatives or context of appropriate use.

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?

Description discloses internal mechanism (55-rule engine, taint-flow simulation, CVSS scoring) and output structure. No annotations exist, so description carries full burden. It omits operational details like file size limits or authentication needs, but is largely transparent.

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?

Well-structured with bullet points, example, and front-loaded purpose. Slightly verbose in listing vulnerability types that are also reflected in findings structure, but overall 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?

Complete for a SAST tool: explains input parameters, internal engine, and full output schema (findings with rule details, risk score, counts, top fix). No missing critical information.

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 has 0% description coverage, but description adds meaning: 'content' is source code, 'source' is file path for language detection with an example. This fully compensates and goes beyond 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?

Description clearly states the tool scans code for security vulnerabilities (SAST analysis) and lists specific vulnerability types (hardcoded secrets, SQL injection, etc.). This is a specific verb+resource combination that distinguishes it from siblings like 'security_scan' and 'compile_docs'.

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. Sibling tools exist (e.g., 'security_scan', 'analyze_codebase_health') but the description does not differentiate usage contexts or provide when-not-to-use information.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool scans every fragment and returns an aggregated report with specific fields. It does not mention any destructive effects or auth requirements, but as a read-only report generation, the description is sufficient.

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 and well-structured: one sentence for purpose, then bullet-pointed output details. No extraneous information, and the main action is front-loaded.

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

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

Given zero parameters and an output schema that exists, the description fully explains the tool's behavior and return format. It is complete for a parameterless tool with a clear output.

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

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

The tool has zero parameters, and schema coverage is 100% by default. The description adds value by detailing the output structure, which compensates for the lack of parameter documentation. Baseline is 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 generates a session-wide security audit across all ingested fragments, listing specific output items. It differentiates from sibling tools like security_scan by emphasizing the aggregate 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?

The description implies use for a macro-level security view ('across all ingested fragments'), but does not explicitly state when to use this tool vs alternatives like security_scan or scan_for_vulnerabilities. No when-not or alternative 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?

With no annotations, the description carries the burden of behavioral disclosure. It lists specific threat types detected, implying a read-only scan operation. It does not explicitly state it is non-destructive or mention authorization needs, but the detailed detection list adds transparency.

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 well-organized: a concise opening sentence, a clear bullet list of detections, a usage instruction, and an Args section. Every sentence adds value without 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?

Given the security scanning complexity and the presence of an output schema (which covers return values), the description provides a complete picture: what it detects, how to use it, and parameter details. No gaps identified.

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 description includes an 'Args' section that explains both parameters ('content' and 'source') with their purpose, compensating fully for the 0% schema description coverage. This goes beyond the schema which only provides types and titles.

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 'Scan content for prompt injection attacks and security threats' and lists specific detection categories. This distinguishes it from sibling tools like 'scan_for_vulnerabilities' which likely targets software vulnerabilities, and 'security_report' which generates reports.

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 instructs 'Use this to verify untrusted content before including it in prompts,' providing clear when-to-use guidance. However, it does not mention alternatives or when not to use, which would elevate the score.

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

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

With no annotations, the description fully carries behavioral disclosure. It details the automatic resolution tiers, token-budget handling, the `over_budget` reporting, `structure_backend="full-fallback"`, the opaque handle for repeated delivery, and the raw-text behavior of full/line-range reads. This leaves little ambiguity about tool 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?

Though lengthy, the description is tightly structured: a clear opening, grouped resolution behaviors, an evidence-based usage note, and a parameter list. Every sentence adds necessary information; no filler or repetition. This is appropriately sized for a 9-parameter tool.

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 all important aspects for a complex read tool: default behavior, switchable modes, edge cases (diff fallback, over_budget), repeated-delivery handles, line-range constraints, and raw-text versus JSON wrapping. It is fully complete given the schema and absence of annotations.

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%, but the description compensates exhaustively. Every parameter is explained in an Args section, including interdependencies ('`previous_source` is required when resolution is "diff"', '`line_start`... cannot be combined with `resolution`') and semantic details like budget, fresh bypass, and read_scope isolation.

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 statement: 'Read a file at an automatic or caller-chosen resolution.' It clearly explains the tool's core function and differentiates its resolution levels, going well beyond a mere restatement of the name.

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 guidance with measured evidence: 'Automatic selection is the right default and cannot be right for every question... Pass `resolution` when you already know which kind of question you are asking.' It also instructs to use `resolution="full"` for exact source text, and explains when line ranges and `fresh=true` are 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?

With no annotations provided, the description carries the full burden. It mentions the listener is 'background' and 'long-running', but does not disclose behavioral traits like resource consumption, cancellation mechanisms, or mutability. Minimal transparency for a background watcher.

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 extremely concise with two sentences, front-loading the key purpose. Every word adds value 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?

Given 4 optional parameters with 0% schema coverage and no output schema guidance in description, the tool is not fully specified. Missing details on parameter usage, stopping the listener, and return values make it incomplete for effective agent use.

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%, yet the description provides no information about any of the 4 parameters (directory, max_files, interval_s, force_initial). The agent has no guidance on what these parameters mean or how to use 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 clearly states the tool's purpose: 'Start a background workspace listener that continuously feeds repo changes into CogOps.' It uses a specific verb ('Start') and resource ('workspace listener'), and distinguishes this as a long-running, change-driven bridge, which is unique among 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 implies usage for continuous monitoring of repo changes, but does not explicitly state when to use this tool versus alternatives (e.g., sync_workspace_changes). It lacks when-not or alternative guidance, leaving the agent to infer 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?

With no annotations, the description provides moderate transparency by detailing that it marks beliefs stale, recompiles, runs verification, and writes a sync report. However, it does not disclose side effects like potential data loss, required permissions, or error conditions.

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, front-loading the purpose and then listing steps. It is well-structured and efficient, though the parameter omission is a downside.

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 complexity (3 undocumented parameters, no annotations, output schema exists), the description is incomplete. It explains the workflow but omits parameter semantics and return value details, which are necessary for an agent to use 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 description coverage is 0%, yet the description does not explain any of the three parameters (force, directory, max_files). This is a critical gap because the agent has no guidance on how to use these parameters.

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

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

The description clearly states the tool synchronizes workspace file changes into belief and verification layers, listing specific steps like detecting changes and recompiling beliefs. However, it does not differentiate from similar sibling tools like refresh_beliefs or verify_beliefs, which slightly reduces clarity.

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 on when to use this tool versus alternatives such as process_change or start_workspace_listener. The description implies usage after source file changes but lacks exclusions or context for optimal use.

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