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 the endpoint parameter is required for the 'local' provider, which is useful. However, it lacks details on edge behavior such as duplicate-name handling, overwriting, or validation failures, leaving the agent without a complete picture of 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 follows a clean docstring format with an initial action statement, a brief context line, and clearly separated Args/Returns sections. Every sentence contributes useful information without redundancy, making it both structured and 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?

For a simple catalog-addition tool, the description covers the core purpose, all parameters, and the return format, especially with an output schema present. It is missing potential edge-case behavior (e.g., duplicate names, provider validation), which prevents a perfect score in a context with no annotations and no schema descriptions.

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

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

The input schema has 0% description coverage, so the parameter details in the description are essential. It explains each parameter's meaning, provides examples for name and model_id, enumerates valid values for provider and tier, and clarifies that endpoint is required for 'local'. 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 action with a specific verb and resource: "Add a new model to the catalog." It also specifies the post-addition effect (usable as stage default or in fallback chains), which differentiates it from sibling tools like remove_catalog_model or update_stage_model.

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 conveys that this tool is the first step for making a model available for stage defaults or fallback chains, implying a clear use case. However, it does not explicitly mention when not to use it or provide alternatives for updating/removing models, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the multi-step workflow (classify, extract, cross-reference), mentions the use of a vision model, and clarifies that it does not ingest new knowledge. It also notes the return format, providing solid behavioral context.

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

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

The description is well-organized with a short intro, numbered workflow, usage guidance, args, and returns. It avoids filler but includes useful detail like example model and path; slightly long but each part contributes.

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, workflow, usage boundaries, parameter semantics, and return value. Given the tool's complexity and the existence of an output schema, it is sufficiently complete and contextualized.

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 compensates by explaining image_path as an absolute path to an image file, with the typical Telegram download path as an example. It also lists accepted formats (PNG, JPG, etc.), adding practical meaning beyond the bare schema field.

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

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

The description names a specific verb ('Analyze') and resource ('circuit schematic or any technical image') and differentiates from siblings by mentioning the VLM + knowledge graph workflow. It clearly states the tool's scope, unlike a tautology.

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

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

It explicitly states when to use the tool ('when a user sends a circuit schematic and wants engineering insights grounded in the knowledge base') and when not to ('NOT for ingesting the circuit as new knowledge'). It names an alternative for a different task ('use ingest_pdf() instead'), satisfying the when/when-not/alternatives requirement.

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 transparency burden. It discloses a 'clean abstention' on insufficient context, and explains that citations can be verified with get_evidence, giving agents a clear behavioral model. However, it does not explicitly state whether the operation is read-only or describe other failure modes.

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 four sentences, front-loaded with the primary purpose, and each sentence adds meaningful detail about verification, downstream integration, or abstention. 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?

For a simple Q&A tool with an output schema, the description covers key workflow aspects: grounding, citations, verification, and abstention. It does not mention prerequisites or alternatives explicitly, but given the tool's low complexity, 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?

The only parameter is 'question' with a string type. The description fails to elaborate on question format, length, or examples, adding no meaning beyond the schema's type and name. Since schema coverage is 0%, the description should have compensated but does not.

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

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

The description opens with 'Answer a question grounded in the knowledge graph, with citations,' which clearly specifies the action, resource, and output. It distinguishes itself from sibling tools like query_knowledge by emphasizing citations and the downstream use of returned concepts.

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 the tool is for getting cited answers, with chunk ids verifiable via get_evidence, and returned concepts feed write tools for hypotheses and decisions. It implies when to use it but does not explicitly exclude alternatives or name tools to prefer in other scenarios.

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 transparency burden. It discloses that the tool is advisory, not a hard gate, verifies only the citation boundary, and does not evaluate structure, ordering, depth, or selection. It also states exactly what conditions are checked (certified claims must cite, all claims must have tiers), giving the agent complete behavioral 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 is somewhat wordy with the Args/Returns docstring format, but every sentence provides valuable information. The structure is logical and front-loaded with the core purpose, followed by scope exclusions and the input/output spec. The length is justified by the tool's complexity, though a slightly tighter phrasing could improve conciseness.

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 full context: when to use it, what it verifies, what it ignores, the exact input format, and the return report structure. Even though an output schema exists, the description's explanation of the return fields and their meaning helps the agent understand the tool's behavior without needing to parse the schema separately. No significant gaps remain.

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 is minimal (just a string parameter with 0% description coverage), so the description must compensate. It provides the complete internal JSON structure, including required fields, allowed tier values, and the condition for cites. This fully compensates for the lack of schema-level detail, adding essential meaning beyond the parameter name.

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 ('verifies') and resource ('claim citations in a lesson'), clearly identifying the tool's function. It differentiates itself from siblings by focusing on the one boundary that matters and explicitly stating it is not a hard gate, making its unique purpose unmistakable.

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 for when to use it ('Advisory self-check for a lesson before you teach it') and explicitly states exclusions ('judges nothing else'), covering when-not. However, it does not name alternative tools or explicitly say 'use this instead of X', preventing a perfect 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 carries the burden of disclosing side effects and state changes. It only states the action and that it returns a confirmation, but does not explain whether ending a session is destructive, reversible, or requires an existing session. This is a significant gap for a state-changing 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 core sentence is concise and front-loaded, but the docstring formatting with Args/Returns adds a bit of redundancy. It is still well-structured and every sentence contributes meaning.

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

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

Given the tool's simplicity (one optional parameter and a simple confirmation return), the description covers the basic purpose and parameter semantics. However, it lacks usage context and behavioral details, making it minimally viable but not complete.

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

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

Although the schema coverage signal is 0%, the description itself includes an Args section explaining `summary` as "Brief summary of what happened in the session." This adds meaning beyond the schema's default empty string, making the single parameter's purpose 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 ("End") and a clear resource ("the current session"), which clearly distinguishes it from siblings like `start_session` and `shutdown`. The action is unambiguous: ending an active session.

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

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

No guidance is provided on when to use this tool versus alternatives like `start_session` or `shutdown`. The description does not mention any prerequisites (e.g., an active session) or contrast with lifecycle siblings, so an agent gets no context for tool 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, the description must carry the full behavioral burden. It does disclose output structure (YAML frontmatter, wikilinks) and the return summary, but omits potential side effects such as overwriting existing files, creating directories, or requiring an existing vault. This leaves notable gaps 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?

The description is concise and well-structured: a clear first-sentence action, a brief format explanation, then Args/Returns. Every sentence contributes, with no redundant text or excessive 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?

For a simple tool with one optional parameter, the description covers the main aspects: purpose, output format, parameter default, and return type. The existence of an output schema covers return structure. However, it could improve by addressing whether the vault is created if missing or whether files are overwritten, which is relevant context for a file-writing operation.

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 explains vault_path's purpose and default value, which the schema does not (0% schema coverage). However, there is a mismatch between the schema default (empty string) and the description's stated default (~/Semiconductor), introducing ambiguity and reducing the value of the added semantics.

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

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

The description starts with a specific verb 'Export' and resource 'knowledge graph' to 'Obsidian vault as Markdown files', clearly distinguishing it from sibling tools like query_knowledge or answer_question. It fully communicates the tool's function 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 provides clear context: 'Open the vault in Obsidian to browse and visualize the graph' indicates the intended use case. However, it does not explicitly name alternatives or state when not to use this tool, though its unique export purpose makes the usage fairly obvious.

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 burden of behavioral disclosure. It explains the core algorithm (shared neighbors, not directly connected) and notes the return type. While it doesn't discuss side effects, permissions, or limits, the tool is clearly read-only, and the description adds meaningful detail beyond the tool's name.

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 one-line summary, a detailed explanation, and separate Args/Returns sections. It is appropriately sized but includes a Returns note that is somewhat redundant given an output schema exists. Still, every sentence contributes to understanding.

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

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

The tool is simple (one parameter, output schema present), and the description covers purpose, methodology, parameter semantics, and a high-level return. It doesn't mention prerequisites or edge cases, but for a find tool of this nature, the provided information is sufficient for an agent to invoke it correctly.

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

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

Schema coverage for parameters is 0%, so the description must compensate. It explicitly explains the sole parameter, 'limit', as the maximum number of bridges to return, which fully conveys its semantics and default behavior. This is a complete and clear description for the parameter.

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

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

The description clearly states the tool's function: finding potential cross-domain connections in the knowledge graph. It provides a specific verb ('Find'), a resource ('knowledge graph'), and distinguishes itself from siblings by explaining the unique criterion (concept pairs sharing neighbors but not directly connected).

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

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

The description implies a use case ('candidates for new insights') but does not explicitly mention when to use this tool versus alternatives, nor does it name any sibling tools. It offers some context but lacks direct guidance or exclusions.

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 transparency burden. It discloses the return format (JSON payload with listed fields) and clearly indicates a read-only operation via 'Read', which implies no side effects. It does not mention error behavior or access requirements, but for a simple read tool this is reasonably 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 well-structured with a brief summary, a redundant Korean translation, and clearly labeled Args/Returns sections. The Korean duplicate adds minimal value but the overall length is appropriate and information is front-loaded. Minor redundancy prevents a 5.

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

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

For a tool with a single parameter and an output schema, the description is complete: it explains when to use it, what input is expected, and what return fields to expect. No additional context is needed for the agent to invoke it correctly.

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

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

The schema only defines chunk_id as a string with 0% description coverage, but the description compensates fully by explaining that chunk_id is the SourceChunk ID returned by query_knowledge. This provenance information is crucial for correct usage and goes well beyond the bare schema.

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

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

The description clearly states the tool's purpose: reading SourceChunk evidence for citation verification. It distinguishes itself from query_knowledge by explicitly referencing chunk IDs obtained from query_knowledge, and the verb 'Read' plus resource 'SourceChunk' make the operation 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?

It provides clear context that this tool is used for citation verification when a chunk_id is already known from query_knowledge context/citations. While it doesn't explicitly mention when not to use it, the dependency on query_knowledge output implicitly differentiates it from related tools like audit_citations.

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

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

With no annotations, the description carries the full burden. It discloses that the tool returns a human-readable summary, lists the specific information included, and states that no arguments are needed. It lacks explicit mention of side effects, but for a getter, this is adequate and above average.

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 and a bulleted list of return contents. Every line adds value, and no words are wasted. The formatting improves skimmability without excessive 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?

For a zero-parameter getter with an output schema present, the description is complete: it explains what will be returned, the prerequisite, and the lack of arguments. The output schema can handle the return value details, so the description need not go further.

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 zero parameters, so the baseline is 4 per the rubric. The description reinforces this with 'No arguments needed.' The input schema is empty, so there is no additional parameter semantics to add.

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

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

The description begins with a specific verb+resource: 'Get the current pipeline configuration', and explicitly lists the contents (stage models, fallback chains, model catalog). This clearly distinguishes it from sibling mutation tools like update_stage_model or add_catalog_model.

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 prerequisite ('Call startup() first') and implies its use as a read-only inspection tool. However, it does not explicitly name alternatives or state when not to use it, 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?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly indicates a read-only operation ('Get', 'Returns') and specifies the categories of data returned. However, it does not mention any potential side effects, access requirements, rate limits, or data freshness considerations, though the absence of such is unsurprising for a simple statistics 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 two short sentences with the main verb and object front-loaded. Every phrase adds meaning: 'system-wide' scopes the tool, and the list of returned items directly informs the agent. There is no redundancy or filler.

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

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

Given the tool's simplicity (no parameters, output schema present), the description is complete. It explains the purpose and the specific data returned, which is sufficient for an agent to decide whether to invoke it. The existence of an output schema further reduces the need to detail return structures.

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

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

The tool has zero parameters, and the input schema is empty. Since there are no parameters to document, the description need not add semantic detail. The baseline of 4 for parameterless tools applies here, and the description's mention of what the stats include is sufficient.

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

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

The description clearly states a specific verb and resource: 'Get system-wide statistics.' It enumerates the returned contents (node counts, memory stats, reinforcement metrics, available skills, configured models), making its scope unmistakable and distinguishing it from sibling tools focused on narrower or domain-specific queries.

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

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

The description provides no guidance on when to use this tool versus alternatives. It simply states what the tool does without mentioning prerequisites, scenarios, or exclusions. There is no comparison to sibling tools such as query_knowledge or get_pipeline_config, leaving the agent to infer usage from the name alone.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It transparently outlines the multi-step process: extracting concepts/equations/parameters, matching against existing knowledge, reasoning about relationships, and committing changes. This reveals that the tool modifies the knowledge graph, which is crucial behavioral information.

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 one-sentence summary, a detailed process description, and an Args/Returns section. It is not overly verbose for a tool with multiple steps and parameters, and the most critical information (purpose, parameters) 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?

For a complex tool involving extraction, matching, reasoning, and committing changes, the description provides a solid overview of the workflow and output. It benefits from an output schema (stated as present), so return value details are not needed. Minor gaps include lack of prerequisites like file accessibility or idempotency, but the description is largely complete for an agent to understand the tool's role.

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 includes an Args section that explains each parameter: file_path as an absolute path, extraction_model and reasoning_model as optional model names. This adds meaningful context beyond the bare string types and defaults, helping the agent understand what values to 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 opens with a specific verb 'Ingest a PDF document into the knowledge graph,' clearly identifying the resource and action. It further details the steps (extracts concepts, equations, parameters; reasons about relationships) that distinguish it from sibling tools like analyze_circuit_image or query_knowledge.

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

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

The description clearly implies this tool is for ingesting PDF documents into the knowledge graph, providing a clear context for when to use it. It lacks explicit exclusions or mention of alternative tools for other input types, but the PDF-specific scope prevents confusion with image-analysis or query 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, the description carries the burden. It discloses the operation type (listing), ordering by confidence, and inclusion of linked concepts, but does not explicitly state read-only safety, sorting direction, or potential side effects. It is adequate but not thorough.

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 statement upfront, followed by concise usage guidance and a compact Args/Returns section. Every sentence earns its place, and there is no redundancy.

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

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

The tool is simple (one optional parameter, output schema present). The description covers purpose, usage, parameter meaning, and return format. Minor gaps like sorting direction do not significantly hurt completeness given the simplicity and existing output schema.

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

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

Schema description coverage is 0%, and the description fully compensates for the only parameter by explaining 'limit' as 'Maximum number of hypotheses to return.' This adds clear meaning beyond the schema's type/default, though it 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 immediately states a specific verb ('List') and resource ('open (unresolved) hypotheses') with clear scope and ordering. It distinguishes this tool from siblings like record_hypothesis or find_bridges by focusing on listing existing unresolved hypotheses.

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?

Two explicit use cases are given: reviewing pending hypotheses for bench verification and finding hypotheses related to a current issue. However, it does not mention exclusions or name alternative tools, so it stops short of full 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 provided, so the description carries the full burden. It discloses destructive behavior ('permanently deleted'), the exact steps performed (gap-fill, edge rewiring), and idempotency of MERGE operations, fully disclosing 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 well-structured with a lead sentence, numbered steps, and parameter definitions. Despite its length, each sentence contributes useful information with no filler.

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

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

For a destructive graph operation, the description covers purpose, workflow, parameters, return value, and discovery alternatives. It is self-contained even without annotations or output schema.

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

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

Schema coverage is 0% (params only typed as string), and the description adds crucial meaning by defining primary_id as the canonical node and duplicate_id as the node to absorb and delete, going well 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 states a specific verb ('Merge') and resource ('duplicate concept node into the primary'), and clearly distinguishes from siblings like retract_node or reinforce_concept by explaining the re-wiring and consolidation 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?

Provides explicit when-to-use (LLM extracted same concept twice with slightly different names) and references alternative tools for finding candidates (query_knowledge, find_bridges).

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 crucial behaviors: runs real ngspice, is additive (existing nodes never modified), guarantees NO-PHANTOM links, and is non-destructive in dry-run mode. This goes well beyond the schema and gives the agent a full safety profile.

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

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

The description is information-dense yet well-structured, front-loading the core purpose and then adding essential behavior details, parameter explanation, and return format. Every sentence earns its place, including the LONG-RUNNING warning and NO-PHANTOM guarantee. The Args/Returns section is a clear, efficient format.

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 tool's complexity and minimal schema, the description is complete: it covers purpose, side effects, safety, long-running nature, dry-run behavior, the one parameter, and the precise return JSON structure. It leaves no significant gap for an agent to choose and invoke the tool correctly.

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

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

Schema coverage is 0% and the only parameter 'apply' is not described in the schema beyond its title. The description compensates fully by explaining 'True to write the projection; False (default) for a dry-run preview', which adds rich semantic meaning beyond the structured field.

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 and resource: it 'Build[s] + project[s]' validated executable-circuit specimens onto the knowledge graph, specifically adding Specimen/ClaimCard nodes and REALIZES/GROUNDS links. It distinguishes itself from sibling tools like retract_executable and query_executable by describing its additive build/projection 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 gives practical usage context: it warns that simulations are long-running, defaults to dry-run mode (apply=False), and explains when apply=True is needed. It does not explicitly name alternative tools for exclusion, but the usage signals are clear enough 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 clearly marks the operation as 'Read' (implying read-only), and adds valuable nuance about the deterministic oracle, the distinction between certified QUANT assertions and interpretive NARRATIVE, and knowledge graph links. It omits auth/rate-limit details but is sufficient for a query 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 dense but well-organized with an intro, Args, and Returns sections. Every sentence contributes meaningful detail, though it is longer than strictly necessary; the structure aids readability and reference.

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?

Paradoxically, the description includes a fully detailed Returns JSON structure, obviating the need for a separate output schema. It covers conditions (corner/temp/vdd), PDK, tools, and knowledge graph connections, making the tool's behavior and result format completely transparent for its 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 only provides a type and default for topology_class, while the description explains its meaning with an example ('miller_ota_2stage_nmos_in') and explicitly defines the empty string as 'all'. 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 begins with 'Read the executable-circuit substrate', a specific verb+resource, and further details 'simulation-VERIFIED circuit specimens and their claim-cards', clearly distinguishing it from sibling tools like query_knowledge or get_evidence by focusing on oracle-certified quantitative claims versus interpretive narratives.

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

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

It identifies the tool as 'the evidence layer for teaching', providing clear context for when to use it (when oracle-certified quantitative facts are needed). It also warns that the mechanism narrative must not be taught as oracle-certified fact, but does not explicitly name alternative 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. It discloses the JSON envelope structure and provides critical caveats: 'when you use a derived item in an answer, label that part of your answer as derived/unverified' and 'chunk claims can be verified verbatim via get_evidence.' This adds meaningful behavioral context about data provenance and reliability beyond a simple query 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?

The core purpose is front-loaded in the first sentence, followed by organized Args/Returns sections. The description is lengthy but every element serves a purpose, such as explaining how to pass concept IDs to record_hypothesis and other tools. It is efficient for the complexity it covers.

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

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

For a tool with complex output (concepts, open_hypotheses, active_decisions), the description thoroughly explains the return structure and connects it to downstream tools. It lacks error-condition or failure-mode information, but given the rich output schema context, it is largely complete for an agent to select and invoke the tool correctly.

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

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

The only parameter 'query' is described as 'Natural language query' with a concrete example ('MOSFET amplifier gain'). Since the input schema provides only a title and type with 0% description coverage, the description fully compensates by specifying the expected format and giving a clear usage example.

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 it 'Query the knowledge graph and memory for relevant information' and explicitly says 'Searches both the Neo4j knowledge graph and the memory system.' This specific verb+resource combination distinguishes it from siblings like recall_memory (memory only) and get_evidence (evidence chunks).

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 the tool by mentioning both knowledge graph and memory and returning hypotheses/decisions, suggesting it is the general retrieval entrypoint. However, it does not explicitly state when not to use it or name alternative tools, leaving the agent to infer the boundary with recall_memory or answer_question.

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 searches only memories and returns formatted text, which implies a read-only operation. However, it lacks explicit statements about side effects, auth requirements, or limitations beyond the scope.

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 short introductory sentence, a usage note, and a compact Args/Returns block. Every sentence adds value, and the format is easily scannable.

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

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

For a simple one-parameter search tool, the description covers purpose, usage, and return format. The presence of an output schema reduces the need to detail return structure. The only minor gap is omitting potential result limits or ordering, but this is acceptable given the tool's simplicity.

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

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

The schema has 0% description coverage, so the description must compensate. It defines 'query' as 'What to search for in memories', which adds meaningful context beyond the bare parameter name. While brief, it sufficiently clarifies the parameter's purpose.

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 'Search memories only (without knowledge graph)', which specifies the verb (search), resource (memories), and scope (excludes knowledge graph). This strongly distinguishes it from sibling tools like query_knowledge, making the purpose unambiguous.

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

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

The phrase 'Useful for recalling past conversations, lessons, or facts' provides clear context on when to use this tool. It implies an alternative for knowledge graph queries, though it doesn't explicitly name a sibling tool or state exclusions.

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

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

With no annotations, the description carries the full burden. It discloses the key side effect: testing a hypothesis automatically updates its status. It also states the return value. Though it doesn't discuss permissions or failure modes, the main behavioral trait is well covered.

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 sections for summary, context, args, and returns. Every sentence adds value, and the length is appropriate for the 7-parameter tool. It front-loads the purpose clearly.

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 operation, side effects, all parameters, and the return value. Given the tool's complexity (7 params, 3 required) and lack of annotations, this is a complete description that would allow correct invocation.

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

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

Schema coverage is 0%, so the description must compensate. It provides detailed explanations for all 7 parameters, including examples and default values (e.g., corner, bench_type, confirms). This fully compensates for the sparse 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 records a simulation or measurement result and optionally links it to a hypothesis. This distinguishes it from sibling tools like record_hypothesis and record_decision by specifying the resource ('bench result') and the linking behavior.

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

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

It provides clear context by mentioning the hypothesis→bench→feedback loop, implying when to use it. However, it lacks explicit 'when not to use' or named 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?

With no annotations, the description carries the burden. It conveys that the tool records persistent decision information and returns a decision ID, and it describes what data is stored. However, it does not disclose details such as permission requirements, idempotency, error handling, or what happens if referenced concept/hypothesis IDs are invalid.

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 and front-loaded, with the purpose stated first and a clear Args/Returns layout. It is slightly verbose due to some redundancy between the opening sentence and the 'Captures WHY...' explanation, but it remains efficient and readable.

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 six untitled parameters, no annotations, and an output schema that only says 'The decision ID', the description is largely complete: it covers purpose, every parameter, and return value. It lacks guidance on prerequisites or inter-tool relationships (e.g., whether concept IDs must exist), but the core usage is well explained.

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 fully by explaining every parameter in the Args block with concrete examples (e.g., choice 'Folded cascode OTA', constraints 'VDD=1.2V, area<100um2'). It also clarifies semantic relationships like 'motivated_by' and 'related_concepts', which the bare schema leaves ambiguous.

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: 'Record a design decision with rationale, alternatives, and constraints.' It clearly explains what the tool does and what it captures, and distinguishes it from sibling tools like record_hypothesis or record_bench_result by focusing on design decisions.

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: it is for capturing design decisions and enabling re-evaluation when specs change. It does not explicitly state when not to use it or name alternatives, but the purpose is distinct enough within the sibling set, giving strong implied 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?

With no annotations provided, the description carries the full burden. It discloses that the operation writes to memory and returns a memory ID, which is useful context. However, it omits details about failure conditions, persistence guarantees, or append-only semantics, leaving the behavioral disclosure 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?

The description is concise and well-structured, with a one-sentence summary followed by clear Args and Returns sections. Every line serves a purpose 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 the tool's simplicity (2 parameters, no annotations, output schema exists), the description covers the essential aspects: purpose, parameters, and return value. It lacks prerequisites such as an active session, but overall it is adequately complete for a basic event recorder.

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 compensates by defining both parameters: event_type with examples and content as 'The event content'. The event_type explanation adds meaningful semantics beyond the schema, though content is minimally described.

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 the tool's action, 'Record an event', and scopes it to 'the current session', with examples of event types (user_message, agent_response, observation). This clearly distinguishes it from sibling recording tools like record_hypothesis or record_decision.

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 generic session event logging via the event type examples, but it does not explicitly state when to use this tool vs. alternatives, nor does it provide exclusions. The guidance is implied rather than explicit.

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

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

With no annotations, the description carries the burden. It reveals that hypotheses are tracked in the knowledge graph, can be confirmed/falsified by bench results, and that the tool returns the hypothesis ID. This provides meaningful behavioral context beyond a simple 'record' verb.

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 and front-loaded with the core purpose. Each section (context, args, returns) earns its place, and the example for statement is concise and illustrative. No redundancy or 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 the tool's moderate complexity (4 params, no annotations, no output schema), the description is complete: it states purpose, usage context, parameter semantics, and return value. It covers all necessary information for invocation.

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

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

Schema coverage is 0%, so the description fully compensates by explaining every parameter: statement with an example, assumptions as comma-separated, test_plan as verification method, and related_concepts as IDs to link. This adds rich semantic meaning beyond the bare 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 records a testable hypothesis about a circuit or design issue, and distinguishes it from sibling tools like record_decision or record_bench_result by specifying the knowledge graph tracking and confirmation/falsification by bench results.

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

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

It explicitly says 'Use this when exploring root causes, predicting behavior, or proposing explanations,' providing clear usage context. It does not explicitly name alternatives or exclusions, but the guidance is sufficient for an agent to choose it appropriately.

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

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

With no annotations, the description carries the transparency burden. It discloses that lessons persist across sessions and are 'curated semantic memories,' which is useful. But it does not cover duplication behavior, whether existing lessons with the same text are updated, or any permission/ownership implications.

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 well-structured docstring with a clear one-sentence summary followed by compact Args/Returns sections. Every line earns its place, and the format is easy to scan. It could be slightly tighter but is appropriately sized.

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 two-parameter tool with an output schema, the description covers purpose, parameters, and return value. However, it lacks usage context (when to prefer this over other recording tools) and second-order behaviors like how these memories are later retrieved or managed. No annotations exist to fill these gaps.

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

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

Schema description coverage is 0%, so the description must compensate. The Args section adds 'Comma-separated tags (optional)' for tags, which clarifies format and optionality. However, 'lesson: The lesson text' adds little beyond the schema's type and title, providing only minimal semantic enrichment.

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

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

The description clearly states a specific verb and resource: 'Record a durable lesson learned.' It also adds context that lessons are stored as curated semantic memories persisting across sessions, which hints at a distinction from other record_* tools. However, it does not explicitly name alternatives or compare with siblings like record_hypothesis or record_decision.

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

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

There is no guidance on when to use this tool versus other recording tools, no exclusions, and no context about prerequisites. The description only states what it does, leaving the agent to infer when it should be selected.

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 of disclosing behavior. It explains the action (strengthening confidence) but does not mention side effects, reversibility, permissions, or the effect on existing confidence values. This is a significant gap for a state-modifying 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 and well-structured, front-loading the main purpose followed by clear Args and Returns sections. Every sentence adds value without unnecessary verbosity.

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 low complexity (2 params, no nested objects) and the presence of an output schema, the description adequately covers the core functionality, usage context, and return message. It could strengthen completeness by noting error conditions or idempotency, but it is generally 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?

Schema description coverage is 0%, so the description must compensate. It explains concept_id as 'The concept ID to reinforce' and evidence as 'Description of the confirming evidence,' adding meaningful semantic context. However, it does not note that evidence is optional (has a default) or clarify the expected format of evidence beyond 'description.'

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

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

The description uses the specific verb 'Strengthen' with the resource 'a concept's confidence in the knowledge graph,' clearly distinguishing it from sibling tools like merge_concepts and retract_node. It states exactly what the tool does.

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

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

It provides explicit when-to-use guidance: 'Call this when a concept is confirmed during conversation, or when new evidence supports an existing concept.' It does not mention alternatives or when not to use, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden. It discloses the key limitation (cannot remove if in use) and the return behavior ('Confirmation or error if model is in use'). This goes beyond the bare action and informs the agent of likely failure modes.

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 appropriately sized, front-loaded with the main purpose, and uses a clear docstring structure. Every line adds useful information without verbosity.

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

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

For a single-parameter tool with an output schema, the description covers purpose, constraint, parameter, and return. It does not explain domain-specific concepts like 'fallback chain' or whether the operation is irreversible, but these are minor for the tool's simplicity.

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

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

The schema has 0% description coverage, so the description must compensate. It does: 'name: Name of the model to remove' clearly explains the single parameter's purpose. Though minimal, it is sufficient for a simple string parameter.

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

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

The description states exactly what the tool does: 'Remove a model from the catalog.' This is a specific verb+resource pair and clearly distinguishes from sibling tools like add_catalog_model or update_stage_model, which handle other operations.

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

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

It provides clear context for when removal is appropriate, and explicitly states a 'when-not' condition: 'Cannot remove a model that is currently set as a stage default or in a fallback chain.' It does not name alternatives, but the purpose and constraint are clear enough for an AI agent to select it correctly.

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 of behavioral disclosure. It explicitly details the deletion operation: 'DETACH DELETE the Specimen + its ClaimCards (and their REALIZES / HAS_CLAIM / GROUNDS edges)'. It also clarifies safety by stating 'The existing graph nodes the links pointed at are untouched.' This is strong transparency, though it omits details on idempotency or behavior when spec_id is invalid.

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 appropriately sized and well-structured. It opens with a clear purpose statement, followed by technical specifics, guidance, and a structured Args/Returns section. Every sentence adds value, from the scope of deletion to the untouched nodes and return counts, without excessive verbosity.

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

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

For a single-parameter deletion tool with an output schema present, the description is complete. It explains what is deleted, what remains untouched, when to use it, what the parameter means, and what the return JSON contains. No annotation support is needed, and the inclusion of return counts makes this 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?

Schema description coverage is 0%, so the description must compensate. The Args section provides a meaningful explanation: 'spec_id: the content-hash id of the specimen to retract (from query_executable).' This adds clarity about the parameter's type, purpose, and origin, which the schema alone (just a string) does not convey.

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

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

The description starts with 'Reverse a project_executable apply', which clearly states the tool's purpose as undoing a specific sibling operation. It distinguishes itself from the sibling tool 'retract_node' by targeting a 'project_executable' projection and specifying the exact entities affected (Specimen + ClaimCards). The phrase 'Use this to undo a bad projection' further reinforces the tool's specific 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 provides explicit guidance on when to use: 'Use this to undo a bad projection.' This establishes clear context tied to a prior project_executable call. However, it does not mention when not to use it or directly compare it to alternatives like 'retract_node', so it lacks explicit exclusions or alternative recommendations.

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 of behavioral disclosure and excels. It details the exact effects of soft delete (sets retracted=true, remains for audit, excluded from search/retrieval/concept matching, recoverable) and hard delete (permanently removes node and ALL edges, irreversible). It also explains the audit trail via the reason parameter and the return format. This is comprehensive and beyond what any annotation could provide.

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

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

The description is well-structured with sections for usage, soft/hard delete behavior, supported labels, args, and returns. It is slightly verbose but every sentence earns its place by providing critical operational detail. The front-loaded summary makes the core purpose immediately apparent, and the layout aids scanning. No redundancy was found.

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 tool having an output schema (not otherwise shown), the description still describes the return value ('JSON with action taken and whether the node was found'). It covers all necessary context: operation types, side effects, recoverability, irreversibility, supported labels, parameter semantics, and usage triggers. For a tool with 4 parameters and no annotations, this is thoroughly 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 description coverage is 0%, so the description must fully compensate, and it does. Each parameter (node_id, label, reason, hard_delete) is given a meaningful explanation, including defaults and examples (e.g., 'node_id: The ID value (e.g. the concept_id, equation_id, etc.)'). Hard_delete is clearly defined with its default value and boolean semantics. This adds substantial value above the bare schema.

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

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

The description opens with a clear verb+resource statement: 'Retract (soft-delete or hard-delete) a knowledge node.' It specifies both the action (retract) and the resource (knowledge node), distinguishing it from sibling tools like retract_executable. The purpose is unambiguous and fully differentiates from alternatives.

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

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

The description explicitly states when to use the tool: 'Use when a node was incorrectly extracted, is factually wrong, or is a hallucination that slipped through grounding checks.' It also provides usage distinctions between soft and hard delete, including when hard delete is appropriate ('only for nodes with zero useful relationships'). This exceeds mere context by offering explicit exclusions and decision criteria.

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

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

With no annotations, the description carries the burden of disclosure. It explicitly states that the tool not only selects but also executes the skill automatically, and it mentions a fallback message for unmatched inputs. This goes beyond the name and gives useful behavioral context.

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

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

The description is concise, front-loaded with the main purpose, and structured with Args/Returns blocks that add value without redundancy. Every line contributes to understanding the tool's function and output.

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

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

For a single-parameter router tool with no annotations, the description is sufficiently complete. It explains the input, the execution behavior, and the return type. It does not enumerate possible skills, but that is not necessary given the tool's dispatch role and the presence of an output schema.

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

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

The schema only provides a title for user_input with no description, so the description's Args block ('Natural language instruction') adds meaningful semantics. This compensates for the 0% schema coverage by explaining what the parameter should contain.

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 natural language input to the best matching skill and executes it, which is a specific verb+resource combination. It distinguishes itself from sibling tools like query_knowledge or ingest_pdf by acting as an orchestrator that selects among 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 usage is implied: when you have a natural language instruction, use this tool to route it to a skill. However, there is no explicit guidance on when to use this directly vs. calling a specific sibling tool, nor any when-not-to-use conditions or alternatives.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It names the actions ('memory promotion and confidence decay') but does not explain side effects, whether changes are destructive, or any prerequisites. This is insufficient for a maintenance tool that likely mutates the knowledge graph.

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

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

The description is concise, front-loaded with the main purpose, and includes a returns section. Every sentence earns its place, with 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?

Given the tool has no parameters and an output schema, the description adequately covers purpose, usage frequency, and return type. It is complete for a simple maintenance 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 input schema has zero parameters, and schema description coverage is 100%. With no parameters to document, the baseline of 4 applies. The description adds no parameter information, which is acceptable since none exist.

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: 'Run maintenance tasks: memory promotion and confidence decay.' This is a specific verb+resource description that distinguishes it from sibling tools like recall_memory or reinforce_concept, which perform individual operations rather than a batch maintenance routine.

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

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

The description gives explicit usage context: 'Should be called periodically (e.g., daily) to keep the knowledge graph and memory system healthy.' This tells the agent when to use it, though it does not explicitly name alternative tools or when not to use it, which would warrant 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 carry the full behavioral burden. It clearly states the core action but gives no details on consequences (e.g., whether it is graceful, irreversible, or affects ongoing tasks). This is adequate for a simple shutdown 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 a single, front-loaded sentence with no filler or irrelevant information. Every word contributes to its meaning.

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

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

The description is complete for a zero-parameter shutdown tool, especially given the presence of an output schema. It could mention the relaunch path or the finality of the action, but these are not essential for invocation.

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

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

The tool has zero parameters, and the input schema is empty. As per the baseline for 0-param tools, the description does not need to add parameter-level detail, and it appropriately stays silent.

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

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

The description states a specific verb ('Shut down') and a specific resource ('the openclaw-brain agent'), clearly distinguishing it from siblings like 'startup'. There is no ambiguity about what the tool does.

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

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

The description implies the tool is used to stop the agent, and the sibling 'startup' provides the inverse context. However, it does not explicitly state when to use it or mention alternatives, earning a 4 rather than 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 are provided, so the description carries the full burden. It explains the linking/summarization behavior but does not disclose potential side effects such as whether a previous session is ended or if any special permissions are needed. This is adequate but leaves gaps.

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 a one-line summary, explanatory sentence, and Args/Returns sections. Every sentence adds value and the key purpose 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?

For a simple one-parameter tool, the description adequately covers what the tool does and returns the session ID. It could mention the relationship with record_event/end_session more explicitly, but overall it is complete enough.

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 no description for session_id, and schema coverage is 0%. The description compensates by explaining it is an optional custom session ID in the Args section, adding meaningful context 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 starts a new episodic memory session and explains the purpose: events are linked together and can be summarized at session end. This distinguishes it from siblings like end_session and record_event.

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

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

The description implies the tool should be used to initiate a session before recording events, and that the session ends with summarization. It does not explicitly mention when not to use it or name alternatives, but the context is clear.

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 only states the action and the ordering requirement, but does not explain side effects, whether the call is idempotent, what happens if the agent is already started, or what the response contains. This is a significant gap for a state-changing startup operation.

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

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

The description is a single sentence with a clear verb and a crucial usage note. Every word earns its place, 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 the tool's simplicity (0 params) and the presence of an output schema, the description provides the key contextual information: it must be called first. However, it lacks details about idempotency and potential side effects, which slightly reduces completeness for an agent deciding how to handle repeated invocations.

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, and schema description coverage is effectively complete. Per the baseline for 0-parameter tools, the description need not add parameter details, and it doesn't need to compensate for missing schema information.

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

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

The description uses the verb 'Start' with a specific resource 'openclaw-brain agent', clearly distinguishing it from sibling tools like 'shutdown' and other operational tools. The additional requirement 'Must be called before other tools' further defines its role as an initialization 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 explicitly states when to use this tool: before all other tools. This gives an unambiguous ordering constraint, even though it doesn't mention alternatives, the context is clear because startup is the prerequisite for everything else.

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

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

With no annotations provided, the description carries the full burden, and it does exceptionally well: it discloses the triggering condition, the ordering behavior of fallbacks, the precondition that all models must exist in the catalog, and the effect of an empty string clearing the chain. It also states the return type.

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 well-structured docstring: a one-line purpose, a concise explanation of behavior, parameter definitions, and return statement. Every sentence earns its place, and there is 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 the simplicity of the tool, the description covers all necessary aspects: both parameters are fully described, the behavioral context is explained, and the return could be inferred from the schema. It is complete and self-contained.

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

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

The schema has zero description coverage, but the description fully compensates by defining `stage` with its three allowed values, and `models` with a comma-separated format, an example, and the clearing behavior. This surpasses what a schema enum would 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 opens with 'Set the fallback chain for a pipeline stage,' which is a specific verb + resource combination. It then explains the fallback behavior, clearly distinguishing this tool from siblings like update_stage_model which presumably sets the primary model.

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 usage context: 'When the primary model fails (after retries), the system tries each fallback in order.' This tells when the tool's effect is relevant. It does not explicitly contrast with alternatives like update_stage_model, but the context strongly implies the distinction.

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 of behavioral disclosure. It clearly states that changes are applied immediately (in-memory) and persisted to config/default.toml, and notes the prerequisite that the model must exist in the catalog. It also indicates the return type (confirmation). This is meaningful behavioral context beyond the basic 'update' 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 concise and well-structured with a brief summary, Args section, and Returns statement. Every sentence adds value, and the docstring format makes key information easy to parse. No fluff or redundancy.

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

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

For a simple two-parameter mutation tool, the description covers all essential aspects: purpose, prerequisites, immediate effect, persistence, and return value. Given the presence of an output schema, the 'Returns: Confirmation' is sufficient. The tool is simple enough that this description is fully 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 description coverage is 0%, but the description compensates well by documenting both parameters: 'stage' with its allowed values ('extraction', 'reasoning', 'matching') and 'model_name' with concrete examples. This adds significant meaning beyond the bare schema, though it stops short of explaining the semantics of each stage value.

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

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

The description clearly states the tool's function: 'Change the default LLM model for a pipeline stage.' This uses a specific verb ('Change') and resource ('default LLM model for a pipeline stage'), distinguishing it from siblings like add_catalog_model (which adds to the catalog) and update_fallback_chain (which updates fallback chains).

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 contextual guidance: the model must already exist in the catalog and changes are applied immediately and persisted. While it doesn't explicitly mention alternatives or exclusions, the context is sufficient for an agent to know when to use this tool, especially with sibling tools like add_catalog_model implicitly being a prerequisite.

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 full burden. It states create/update and returns the entity ID, but does not disclose idempotency, partial-update behavior, error handling, or whether existing fields are overwritten.

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 compact docstring with a clear opening and structured Args/Returns sections. It is appropriately sized without filler, though the formatting is standard rather than optimized for quick scanning.

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 provides the core purpose, parameter meanings, and return value, which is adequate for a simple CRUD tool. However, it lacks usage guidance, behavioral caveats, and context relative to sibling tools, leaving gaps for an agent navigating a complex toolset.

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

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

Schema description coverage is 0%, but the description compensates by defining each parameter: entity_id as unique ID, entity_type with examples, name as display name, and summary as brief description. This adds meaning beyond the schema, though more format details could be included.

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 explicitly states 'Create or update a semantic entity' and lists example types. This clear verb+resource pairing distinguishes it from siblings like query_knowledge or record_event, which have different purposes.

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

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

No guidance is given on when to use this tool versus alternatives like record_event, merge_concepts, or retract_node. The description only states the basic operation without explaining exclusions, 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?

With no annotations, the description carries the full burden and does so excellently. It discloses a critical behavioral nuance: the QUANT verdict is oracle-certified while the narrative is interpretive and never a fact. It also clearly states the return JSON structure, giving the agent a complete behavioral model.

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 an opening purpose, a critical caveat, and Args/Returns sections. Every sentence adds value, and the formatting makes it easy to scan. It is appropriately sized for the tool's 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?

Even though an output schema exists, the description provides a comprehensive overview: input format, return fields, and the interpretive boundary. For a single-parameter tool with domain-specific nuance, this is more than 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 schema has zero description coverage, but the description fully compensates by explaining claim_card_id's source (query_executable) and exact format ({spec_id}:{claim}). This adds meaning far beyond the bare parameter name 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's function: 'Grounding for one executable-substrate claim-card' and 'Use it to inspect (or cite) a specific sim-verdicted claim.' This is a specific verb+resource combination that distinguishes it from siblings like query_executable (which likely lists claims) and get_evidence (which may retrieve broader evidence).

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

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

It provides clear usage context: use for a specific claim-card id when you need to inspect or cite, and explicitly says the id comes from query_executable with format {spec_id}:{claim}. However, it does not explicitly state when not to use it or mention 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.