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

With no annotations provided, the description carries the burden of disclosure. It mentions the key behavior of releasing the session from the runtime and the context that it is no longer needed. However, it does not discuss reversibility, side effects, or failure modes, leaving 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 two sentences, with the action stated first and a concrete use case following. Every word serves a purpose; there is no wasted text or redundancy.

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

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

The description covers the core action and a typical use case, which is adequate for a one-parameter tool. However, without annotations or an output schema, it does not address return values, error handling, or preconditions, so it is not 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?

The single parameter session_id is fully described in the schema with 100% coverage. The description adds no additional detail about the parameter, such as format or constraints, so the schema does the heavy lifting.

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 'Close a session' and the effect 'releasing it from the runtime.' It also provides a typical use case after merge_branch, which distinguishes it from sibling tools like merge_branch and create_branch.

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 describes when to use the tool: after merge_branch reports success, with the rationale that the source branch has been integrated and no longer needs to stay open. However, it does not mention exclusions or 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?

The description adds useful behavioral context by noting the returned diff is directional and that a semantic summary is included. However, with no annotations, it fails to explicitly state that the operation is read-only or has no side effects, leaving part of the burden unmet.

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 verbose and includes contradictory information about parameters. It would be more effective as two clear sentences, without referencing nonexistent fields or duplicating schema 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 no annotations and no output schema, the description should clarify the exact parameter roles and return structure. While it mentions directional diff and semantic summary, it inaccurately describes parameters and omits any mention of side effects or use cases, leaving the tool incompletely specified.

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

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

The description introduces base_version_id, which is not in the schema, and incorrectly states that target_version_id is the current session state, contradicting the schema's definition of it as the historical version. This actively misleads instead of adding value beyond the schema.

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

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

The description clearly states the tool compares a session's current state against a historical version, which is a specific verb+resource. However, it does not explicitly differentiate itself from sibling tools like explain_diff, reserving the top score.

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

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

No guidance is provided on when to use this tool versus alternatives such as explain_diff or list_versions. The description only explains the operation without contextual usage instructions.

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

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

The description discloses the internal pipeline (LLM extraction, parsing, validation, persistence), provider auto-selection logic (local Ollama vs. Anthropic based on environment), and return values ('session_id', 'version_id', serialized structure). It also mentions that a new session is persisted, implying a side effect. Since there are no annotations, this level of disclosure is strong.

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

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

The description is about four sentences, front-loading the primary purpose. It includes necessary details about provider selection and return values without extraneous fluff. It is compact and informative.

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

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

For a complex tool with 4 parameters and no output schema, the description provides sufficient context: creation process, provider fallback logic, return identifiers, and the hint parameter. It does not explain failure modes or validation errors, but the core invocation path is well covered.

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

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

The input schema already provides descriptions for all four parameters (100% coverage). The description adds little beyond schema – only a brief note about using 'hint'. Parameters like 'model' and 'max_tokens' are adequately explained in the schema, so the description does not need to compensate.

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

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

The description opens with 'Build a Canonical Knowledge Structure from free-form text using an LLM' – a specific verb, resource, and process. It clearly differentiates from sibling tools by stating the output is persisted as a new session, while others like export_knowledge or validate_knowledge serve 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?

The description implies when to use it: when you have free-form text and want to create a knowledge structure. It provides context like using 'hint' to direct extraction, but does not explicitly name alternatives or state when not to use this tool. Since the purpose is distinct and clear, this is acceptable.

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 states 'without touching the parent session', which reveals that the operation is non-destructive to the parent. The fork action implies creation of a new session, and the lifecycle mention of close_session/merge_branch hints at the branch's temporary nature. It does not cover all conceivable side effects (e.g., data isolation level), but the description is reasonably transparent for the tool's complexity.

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

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

The description is two sentences, front-loaded with the core action, then usage context, then lifecycle guidance. Every phrase earns its place; no fluff or repetition. It is concise yet informative.

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 2-parameter tool with no output schema, the description covers the essential context: purpose, when to use, and post-branch actions. It does not explain return values or error behavior, but those may be inferred from the schema and the tool name. The lack of an output schema means the description need not describe return format. Overall, it is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%: both session_id and version_id have descriptive schema text. The description does not add parameter-level detail beyond the schema. Per the rubric, baseline 3 is appropriate when the schema fully documents parameters, and the description provides no additional semantic value for them.

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

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

The description opens with 'Fork a new session from an existing one' – a specific verb and resource that clearly defines the tool's purpose. It further distinguishes from siblings by referencing close_session and merge_branch as lifecycle actions, indicating it is the branching tool in a session-management workflow.

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

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

Explicitly states when to use: 'Use this to isolate an experiment, explore an alternative modeling approach, or try a risky edit without touching the parent session.' It also provides lifecycle guidance (close_session if it fails, merge_branch if it succeeds), which gives clear context. It does not explicitly name alternative tools to use instead, but the guidance is specific enough to differentiate its role.

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 important behavioral traits: inference_confidence_conflict is reported at WARNING severity, not ERROR; it clarifies that it is a resolvable belief conflict; and it instructs how to properly mark steps inactive via 'superseded_by'. These details go beyond what would be expected in structured annotations.

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

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

The description is lengthy but well-structured with clear sections: main purpose, detection types, examples, and practical usage notes. Each section adds value, though the example JSON snippets could be considered verbose. The front-loading of the core purpose is strong.

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 tool's complexity well, explaining three detection types, prerequisites, and even a specific ADR reference. However, since there is no output schema, the description does not explain what the tool returns (e.g., list of contradictions, their locations, severities). This is a notable gap for complete contextual understanding.

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

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

The input schema already provides 100% coverage with descriptions for both json_data and session_id. The tool description does not add significant parameter-specific meaning; its examples and details focus on the detection behavior and rule configurations rather than the parameters themselves. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Detect logical contradictions') and resource ('Knowledge Structure'), and elaborates with three distinct detection types. It distinguishes from siblings by detailing the specific contradiction rules and providing examples, making its unique function immediately apparent.

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 rich usage context, including how to enable detection types (e.g., 'ensure your structure contains MutualExclusionRule and/or FunctionalRelationRule objects') and clarifying that inference_confidence_conflict needs no rule object. However, it does not explicitly compare to alternatives or state when not to use this tool, so it lacks explicit 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool returns a new session_id and version_id, which is a useful behavioral detail. However, it does not disclose potentially destructive side effects (e.g., remove_object cascade-deletes relations), mutation semantics (evolving an existing session vs. creating a new one), or failure modes. This is a significant gap for a tool that can modify or delete knowledge structures.

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

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

The description is two sentences and front-loads the core purpose. The first sentence states what the tool does, and the second sentence provides actionable output information. Every word earns its place. There is no fluff or repetition of schema content.

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 complex (three parameters, one required, operations with many variants) and there is no output schema. The description only mentions the return of session_id and version_id, omitting the overall behavior of applying operators, the meaning of a new session, or what happens when session_id is provided. It gives no hint about the breadth of operations defined in the schema, leaving the agent without a high-level understanding of the tool's capabilities and side effects.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description itself adds no parameter semantics; all details are in the input schema, which is exceptionally thorough with operator types, required fields, examples, and cascade behaviors. The description neither adds nor detracts from the schema, so a baseline 3 is appropriate.

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

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

The description states a clear verb+resource: 'Apply structural evolution operators to a Knowledge Structure.' It also explains the return values (new session_id and version_id). While it doesn't explicitly differentiate from siblings like merge_knowledge or construct_knowledge, the concept of 'evolution operators' is specific enough. The purpose is clear but not maximally distinct from other knowledge-structure tools.

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

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

The description implies usage: you apply evolution operators to a Knowledge Structure. It also mentions that the resulting session_id can be used with list_versions and revert_version, giving some post-use context. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use construct_knowledge for creation or merge_knowledge for combining), nor does it provide any exclusions or prerequisites.

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 discloses that output is 'in plain English' and that it analyzes the 'current state of a session,' suggesting a read-only operation, but it does not explicitly state side effects, permissions, or limitations. This is adequate but lacks explicit clarity on whether any modification occurs.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence adds value. The first sentence defines the operation, and the second explains the use case, with no redundant or filler content.

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 output schema, no annotations), the description covers the core elements: what it does, when to use it, and the nature of its output. It does not specify return details or error scenarios, but these are less critical for an explanation tool. The description is sufficiently complete for the context.

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

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

The input schema has 100% coverage with descriptions for both parameters (session_id and target_version_id). The description adds context by framing the comparison as 'current state' versus 'target version,' but this does not introduce new semantics beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: explaining differences between a session's current state and a target version in plain English. It uses a specific verb ('explain') and resource ('session', 'target version'), and it distinguishes itself from siblings like compare_versions by emphasizing the plain-English output rather than raw diff.

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 by stating it is 'useful for understanding what changed without parsing raw diff output,' which implies the tool is for high-level analysis. However, it does not explicitly name alternative tools (e.g., compare_versions) or state when not to use it, so it falls short of full exclusionary guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it produces an explanation and mentions the session_id condition; it does not disclose whether the operation is read-only, if it has side effects, or what the output format is. This leaves important behavioral traits unexplained.

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

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

The description is two sentences, directly stating the purpose and the optional parameter. It is front-loaded with the primary action and has no filler or 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 no output schema and no annotations, the description should provide more context about what the explanation includes and any behavioral implications. It clearly states the purpose but leaves gaps around output format and side effects, making it only minimally complete for a tool handling complex knowledge 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?

Schema coverage is 100%, and the schema already provides detailed descriptions for both json_data and session_id. The description's mention of session_id adds no new meaning beyond what the schema provides, so it stays at the baseline of 3.

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 produces a human-readable explanation of a Knowledge Structure, which is a specific verb+resource combination. It implicitly distinguishes from siblings like explain_diff (explains differences) and validate_knowledge (validates structure).

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

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

The description gives context for the optional session_id parameter (explaining an existing session vs. creating a new one from json_data), but it does not explicitly discuss when to use this tool versus alternatives like explain_diff or validate_knowledge. Usage is implied rather than stated.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It does not explicitly state that the export is read-only or non-modifying, nor does it describe what happens to the session or what the output looks like (e.g., returned string vs. file download). The word 'Export' implies a safe operation, but this is not made explicit, leaving uncertainty.

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 exactly two sentences, front-loaded with the action verb. Every word earns its place—the first sentence states the core function, and the second lists specifics. There is no filler or redundancy.

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

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

Given the simplicity of the tool (2 params, 1 required), the description covers the basic purpose and formats. However, it lacks information about the return value or output format (e.g., whether it returns the RDF content directly or as an attachment), and it does not differentiate from the similar-sounding sibling 'export_session'. Since there is no output schema, the description should have provided this context.

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

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

Schema description coverage is 100%, so the schema already documents both 'session_id' and 'format' parameters effectively. The description adds minimal extra value by listing the supported format values, but these are already present in the schema's format description. It does not clarify default behavior beyond what the schema already states.

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 ('Export'), identifies the resource ('a session's Knowledge Structure'), and states the destination ('to another format'). It also lists the supported formats ('json-ld', 'turtle', 'rdf-xml'), making the tool's purpose immediately clear. This clearly distinguishes it from generic 'export' tools, though it does not explicitly contrast with the sibling 'export_session'.

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

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

The description implies usage context: use this tool when you need to export a session's Knowledge Structure to a supported RDF format. However, it provides no explicit guidance on when to use this tool versus alternatives like 'export_session' or 'serialize_knowledge', and no exclusions or prerequisites are mentioned.

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

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

The description discloses the output nature (self-contained JSON document), what it includes (version history, metadata), and warns about potentially large payloads when include_structures is set. Since no annotations are provided, this added context is valuable, though it stops short of explicitly stating side effects or required permissions.

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

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

The description is well-organized: a clear purpose statement, a sibling contrast, format details, and a note on the include_structures option. It is reasonably concise for a tool with three parameters, though a minor redundancy with the schema could be tightened.

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

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

Given the absence of an output schema and annotations, the description provides a solid overview of what the tool returns (self-contained JSON, version history, metadata) and includes a size warning. It covers the essential context, though a brief note on non-destructive behavior would have made it 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?

All parameters are described in the schema (100% coverage), giving a baseline of 3. The description adds extra meaning by elaborating on the difference between 'bundle' and 'cks' formats and the implications of include_structures, going beyond the schema's bare definitions.

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

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

The description clearly states the tool exports a full session bundle for migration or archival. It explicitly differentiates from export_knowledge, eliminating ambiguity and making the purpose and scope immediately clear.

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 contrasts with export_knowledge, telling the user when not to use this tool (when RDF/JSON-LD output is desired). It also explains the two output formats and when to prefer each, providing direct guidance on usage.

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 key behaviors: parent session untouched, sandbox is isolated, and it can be safely discarded. It also explains the operations are evolution operations, providing 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?

Two sentences with no redundant content; front-loaded with the main action, then safety note. Every word earns its place.

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

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

For a tool with 4 params and no output schema or annotations, the description covers the core purpose, optional operations, and safety. It also hints at the diff behavior. It lacks return-format details, but the mention of showing differences partially compensates.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds that operations are evolution operations and mentions applying a hypothesis, but its phrasing '(list of evolution operations)' could be misread as defining the hypothesis parameter rather than operations, introducing ambiguity.

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

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

The description uses a specific verb ('Create') and resource ('isolated sandbox branch') and clarifies optional application of operations and diff display. This distinguishes it from sibling tools like create_branch by emphasizing isolation and safety.

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

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

It states the sandbox is for testing a hypothesis and can be discarded if it fails, implying use for safe exploration. It does not explicitly name alternatives or exclusions, but the isolation context ('parent session never touched') provides clear usage context.

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

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

No annotations are provided, so the description carries the full burden. It discloses the internal structure of the return value ('runtime_metrics' and 'tool_telemetry') and the temporal scope ('since the server started'). While it does not explicitly state read-only behavior, the verb 'get' implies no side effects, and the description adds meaningful 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 two sentences long, front-loaded with the main action and object, and then elaborates with relevant details. Every sentence adds value 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?

Without an output schema, the description adequately conveys the return structure by listing the two main sections and key fields. Minor ambiguity around the term 'dashboard' prevents a perfect score, but overall it is complete for a zero-parameter metrics tool.

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

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

The tool has zero parameters, so the baseline is 4. There is no parameter information to provide, and the description correctly focuses on the return value instead.

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

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

The description clearly states the tool returns runtime metrics and a tool telemetry dashboard, using a specific verb ('Return') and resource. It is distinct from sibling tools, which are all knowledge-related operations, so the purpose is unambiguous.

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

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

The description does not explicitly state when to use this tool or mention alternatives. However, its purpose is self-evident and no sibling tool overlaps with metrics retrieval, so usage is implied rather than explicitly guided.

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 bears full responsibility for transparency. It discloses SSRF protection and refusal of private/internal URLs, and describes the linking behavior via 'mentions' relations. However, it does not clarify whether the tool persists the Knowledge Structure or only returns it, leaving side-effect ambiguity.

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

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

The description is two sentences, front-loaded with the primary action, and contains no redundant phrasing. Every clause adds useful 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 simple single-parameter interface and lack of output schema, the description adequately explains the primary function, output structure, and a key behavioral restriction. Minor gap: it doesn't state persistence or side-effects, but this is a relatively simple tool.

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

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

The schema already documents the 'url' parameter as 'The publicly accessible URL to fetch', so coverage is 100%. The description adds meaningful context by emphasizing public access and SSRF refusal, which clarifies failure conditions.

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

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

The description uses specific verbs 'Fetch', 'extract', and 'return' with a clear resource (public URL document) and states the result (Knowledge Structure). It distinguishes this from sibling tools like construct_knowledge or verify_source by focusing on external URL ingestion.

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 publicly accessible web documents but does not explicitly say when to choose this over alternatives like construct_knowledge or verify_source. It provides a constraint (SSRF refusal) but no explicit 'when to use this tool' 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, the description must carry the behavioral disclosure burden. It implies a read-only operation ('List') and mentions a prerequisite, but does not disclose return format, pagination, or whether the session must be active. This adds some context but remains basic.

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

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

The description is two sentences, front-loaded with the core purpose, followed by the prerequisite. 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?

For a simple 1-parameter list tool with no output schema, the description covers the essential: what it does and how to obtain the required input. It could mention the return value shape, but given the simplicity, it is reasonably 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 already describes session_id fully, but the description adds crucial semantics by explaining that the ID comes from specific prior calls. This helps the agent understand where to obtain the value, going beyond the schema's generic 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 clearly states the tool lists all available versions of a session's history, using a specific verb and resource. It distinguishes itself from siblings like compare_versions and revert_version by focusing solely on listing versions.

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: the session_id must come from a previous call to validate_knowledge or evolve_knowledge. While it doesn't explicitly contrast with alternative tools, this gives the agent actionable context for when to use this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It honestly states that on conflict it returns a 'conflicts' list instead of merging, that retrying with resolutions merges everything including previously non-conflicting changes, and that unresolved identities are reported again. It also reveals the commit behavior ("commits the merged result as a new version of the target session"). This is highly 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 a single dense paragraph that front-loads the core purpose and then methodically covers conflict handling, retry semantics, and alternative paths. Each clause earns its place, but the length and density make it slightly harder to parse quickly. It is efficient but not maximally 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?

Given the complexity of a three-way merge tool, the description is remarkably complete. There is no output schema to explain return values, but the description covers the success case, conflict return format, retry workflow, and final cleanup via close_session. It also accounts for the edge case where the user wants to modify the target directly. This is sufficient 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?

Though the input schema already describes each parameter (100% coverage), the description adds significant semantic value. It explains the 'resolutions' parameter in detail, including the behavior of merging everything in one call and the meaning of each resolution value. It also clarifies 'base_version_id' overrides and the roles of source/target session IDs, going beyond the schema's per-parameter 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 opens with a specific verb and resource: "Session-aware three-way merge: merge a branch session's changes into a target session." It clearly distinguishes this tool from merge_knowledge by noting the automatic base resolution and the lack of user-supplied base. This makes the tool's purpose unambiguous and differentiates it from a direct sibling.

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

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

The description provides explicit usage guidance: it contrasts with merge_knowledge ("unlike merge_knowledge -- you never supply the base yourself"), instructs not to call merge_branch unchanged after a conflict, directs the retry with a 'resolutions' argument, and offers an alternative path via evolve_knowledge. It also tells the user to close_session the source branch once fully integrated. This is comprehensive when/when-not 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, the description must disclose side effects and error behavior. It discloses the return behavior (merged structure or conflict list) and the condition for conflicts, but does not mention whether inputs are modified, permissions required, or other potential 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 exactly two sentences, front-loaded with the primary action and clear about inputs and outputs. No wasted words.

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

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

For a tool with four parameters, nested objects, and no output schema, the description covers the core functionality and return types. However, it does not detail the conflict list format or how the optional 'resolutions' parameter interacts with conflict resolution, leaving some gaps for an agent unfamiliar with the domain.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual meaning by framing the parameters as 'independently evolved branches' and explaining the three-way merge scenario, which enriches understanding beyond the schema's property descriptions.

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

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

The description clearly states the tool performs a three-way merge of Knowledge Structures, specifying the exact inputs (base, branch A, branch B) and outputs. This distinguishes it from sibling tools like merge_branch, which likely operates at a different level.

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

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

The description gives clear usage context: provide a common ancestor and two independently evolved branches. However, it does not explicitly state when not to use it or name alternative tools, so it lacks explicit 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 full burden of behavioral disclosure. It discloses the return format (self-contained subgraph, serialized), metadata fields (total_found_nodes, returned_nodes, is_truncated, truncation_reason, suggested_next_seed), and behavior around truncation and budget prioritization via type_weights. This is rich, beyond what a typical description offers.

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, tightly packed with useful information. It front-loads the main purpose in the first sentence, then systematically covers return metadata, filtering, and budget handling. No filler or redundancy.

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

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

For a complex tool with 10 parameters and no output schema, the description covers the essential behavior: what is returned, truncation metadata, and how to control the traversal. The schema handles the remaining parameter details, and the description explicitly lists the metadata fields, making the output understandable without 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 input schema already covers all 10 parameters with descriptions (100% coverage), so the baseline is 3. The description adds strategic guidance on how parameters interact: filters narrow traversal, max_tokens/max_objects cap the result, and type_weights prioritize when truncation occurs. This adds meaning beyond the schema's simple per-parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Extract the local k-hop neighbourhood around one or more seed ids from a session's current Knowledge Structure.' It uses a specific verb ('extract') and resource ('session's Knowledge Structure'), and the mention of 'k-hop neighbourhood' distinguishes it from sibling tools like search_semantic or serialize_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 provides clear usage context: it explains how to narrow traversal with filters and cap results with max_tokens/max_objects. However, it does not explicitly mention when to use this tool versus alternatives or state any exclusions, so it lacks explicit sibling differentiation.

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

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

With no annotations, the description must disclose behavioral traits. It says 'revert,' which implies mutation, but it doesn't state whether the action is irreversible, what happens to the current version, or if branches are affected. This is a significant gap for a potentially destructive operation.

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

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

The description is two sentences, direct, and front-loaded with the action. It wastes no words and delivers the essential information efficiently.

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

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

For a tool with no annotations and no output schema, the description covers the basic purpose and a key prerequisite, but it lacks behavioral details such as whether the revert is irreversible, what the response looks like, or potential side effects. This is adequate but not fully complete for safe invocation.

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

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

The schema already provides descriptions for both parameters (100% coverage). The description adds valuable extra meaning by specifying that session_id must come from a prior call to validate_knowledge or evolve_knowledge, which is not in the schema. It doesn't add detail for target_version_id, but the schema covers it adequately.

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: 'Revert a session's Knowledge Structure to a specific previous version.' It identifies the specific resource (Knowledge Structure) and the target (previous version), which distinguishes it from sibling tools like list_versions or compare_versions.

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 a clear prerequisite: session_id must come from a previous call to validate_knowledge or evolve_knowledge. This gives useful context for when to use the tool, but it doesn't explicitly mention alternatives or when not to use it, so it misses the top tier.

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 explains the vector-index dependency, the background outbox worker, and the seed_ids fallback. It also mentions that the tool expands via query_subgraph. It does not disclose the return format or any side effects, but for a search tool this is acceptable.

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

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

Three sentences, front-loaded with purpose, and every sentence earns its place. It covers the action, the conditional behavior, and the when-to-use guidance 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 6 parameters and no output schema, the description covers the key context: the search mechanism, the fallback, the expansion via query_subgraph, and the applicable use case. It does not describe the return format, but with no output schema and clear param details, this is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra value by explaining the relationship between query and seed_ids, clarifying when each is appropriate, and noting the fallback behavior. This goes beyond the schema's individual parameter 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 opens with a specific action: 'Semantically search the Knowledge Structure of a session.' It clearly distinguishes from siblings by explaining that it uses natural language queries instead of exact IDs and mentions query_subgraph as an internal helper. The resource and scope are well-defined.

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?

Explicit when-to-use guidance: 'Use this when you don't know exact object IDs but have a description of what you're looking for.' It also explains when to pass seed_ids instead, covering both the primary and fallback scenarios. This makes the usage context unambiguous.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states the core action and the session option, but fails to explain side effects (e.g., whether a session is created when json_data is used), the precedence when both parameters are provided, or any auth/rate-limit concerns. This is a significant gap for a serialization 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 concise sentences: the first states the primary action, the second covers the session alternative. Both sentences earn their place with no filler or redundancy.

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

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

The description covers the two main usage modes (json_data and session_id) but lacks details about the return value (exact JSON structure), error conditions, and the meaning of 'canonical' in this context. Given the complexity of the tool and absence of an output schema, this is a moderate gap that could affect 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?

The input schema already provides 100% coverage for both parameters, including a detailed example for json_data. The description only restates the optional nature of session_id without adding new semantic details, so the baseline score of 3 applies.

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

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

The description uses the specific verb 'Serialize' with the resource 'Knowledge Structure' and states the outcome 'canonical JSON representation'. This clearly distinguishes it from sibling tools like validate_knowledge or export_knowledge, 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?

The description provides clear usage context by explaining that session_id is optional for serializing an existing session, implying the alternative of providing json_data for a new structure. However, it does not explicitly mention exclusions or alternatives like export_knowledge, leaving some ambiguity.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool 'commits nothing' and is a dry-run that validates 'the same way evolve_knowledge does internally.' It also discloses the output (current objects/relations and guidance). While it doesn't mention potential side effects like cost or permissions, the non-mutating nature is explicitly communicated.

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

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

The description is three sentences long, front-loaded with the core purpose, followed by usage guidance and the alternative preview mode. Every sentence provides essential information without redundancy or fluff. It's concise and well-structured.

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

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

Given the tool's moderate complexity (two usage modes, dry-run behavior) and the lack of an output schema, the description covers the essential aspects: what it does, when to use it, and that it commits nothing. It names the sibling tool (evolve_knowledge) and the return content. It doesn't detail the exact return structure, but the high-level description is sufficient 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the relationship between the two modes: using `description` alone to get guidance, vs. providing an `operations` list for preview. It also clarifies that `operations` accepts the same format as evolve_knowledge, which is not evident from the schema descriptions alone.

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

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

The description clearly states the tool's function: given a session and a change description, it returns current objects/relations and guidance for constructing valid evolution operations. It also distinguishes itself from the sibling evolve_knowledge by positioning it as a pre-check or dry-run, and from validate_knowledge by focusing on evolution operations. The verb 'return' and resource 'guidance' are specific.

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

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

Explicit usage guidance is provided: 'Use this before evolve_knowledge to reduce trial-and-error.' It also explains the alternative scenario where you already have a candidate operations list and want to preview its validity. The description clarifies when not to use it (when ready to commit) by contrasting with 'spending a real evolve_knowledge call on a guess.'

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 side effects (creation of a session when session_id is absent), the per-call nature of extensions, and the return of a session_id for version tracking. It does not provide exhaustive details on permissions or reversibility, but it gives a reasonably transparent behavioral overview for a validation 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 front-loaded with the core purpose and is divided into short, actionable sentences. It is slightly redundant with the schema but not bloated. Each sentence serves a distinct informative function: purpose, return value, optional modes, and return usage.

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

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

The tool has 3 parameters, a rich schema, and no output schema. The description covers the main aspects: what it validates, optional behaviors, return value, and how the returned session_id can be used with version tooling. It does not detail the exact shape of validation results, but that may be standard for the domain and is adequately summarized as 'validation result and diagnostics'.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaningful new information about parameters beyond what the schema already provides; it merely restates the purpose of session_id and extensions. It does not clarify the format of json_data beyond the schema's detailed 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 opens with 'Validate a Canonical Knowledge Structure', a specific verb+resource pairing that clearly identifies the tool's function. It distinguishes itself from siblings by focusing on validation rather than evolution, construction, or versioning operations. The mention of 'Returns validation result and diagnostics' further clarifies the core purpose.

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

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

The description provides clear context on when to use the tool, including the option to validate an existing session's current state or create a new session, which is a mode selection. It explains how extensions and session_id alter behavior. However, it does not explicitly compare against alternative tools like detect_contradictions or verify_source, so it lacks explicit 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 transparency burden. It discloses the important behavioral trait of performing a 'real HTTP request', which implies network side effects, and mentions the creation of a VerificationRecord. However, it does not discuss potential failures, timeouts, or authorization requirements, so it is informative but not fully transparent.

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

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

The description is a single, concise sentence that packs in the purpose, mechanism, and outcome. Every word contributes value with no irrelevant detail or repetition.

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

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

Given a simple 2-parameter tool with no output schema, the description adequately states what happens (HTTP call, VerificationRecord created). It could include return structure, but the absence of an output schema makes this a minor gap. The description provides enough context 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?

Schema coverage is 100% since both parameters have descriptions in the schema. The tool description does not add further context about the parameters, but it doesn't need to because the schema already defines 'url' and 'subject_id' clearly. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'verify' and the resource 'external source', and specifies that a real HTTP request is made. It also mentions the creation of a VerificationRecord, which distinguishes it from sibling tools like validate_knowledge that might refer to internal validation.

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 'Verify an external source' provides clear context for when to use the tool. However, it does not explicitly mention alternatives or exclusions, relying on the explicit 'external' qualifier to differentiate from other validation 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 full burden. It discloses the output format (Mermaid) and notes that raw Mermaid text is useful even if clients don't render it. However, it does not mention whether the operation is read-only, has any side effects, or requires specific session state, leaving some uncertainty.

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

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

The description is two sentences, front-loaded with the core purpose and followed by a brief usage note. Every sentence earns its place, with no filler or repetition.

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

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

Given the tool's simplicity, the description covers the essential purpose, output format, and usage context. The schema handles parameters, and the description adds the key context about when to use it. It lacks explicit safety or side-effect details, but that is a minor gap for a likely read-only export 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 covers 100% of the parameters with descriptions, so the baseline is 3. The description does not add any additional parameter semantics beyond the schema, making it adequate but not enhanced.

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 ('Export'), a clear resource ('a subgraph'), and a concrete output format ('Mermaid diagram'). This distinguishes it from sibling tools like export_knowledge or serialize_knowledge, which might have different output formats or 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?

The description explicitly states when to use the tool: 'Use this after query_subgraph to show the structure.' It provides clear context but does not mention alternatives or when not to use it, so it falls short of a fully explicit when/when-not guideline.

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