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

The description goes beyond the readOnly/idempotent annotations by disclosing that the default view is a bounded summary, that components/connections use opaque cursors for pagination, and that embedded firmware/geometry require explicit opt-in. These are meaningful behavioral details not present in annotations, enhancing transparency.

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

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

The description is three sentences, each packed with specific information: what is recognized, the default/pagination behavior, and opt-in requirements. No filler or repetition; it is efficiently structured and 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 an 8-parameter tool with low schema coverage, the description covers the most important behavioral aspects, and an output schema exists so return values are not required. Missing context on topologyMode and expectedProjectDigest usage, but overall the description provides a solid context for successful use.

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

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

With only 25% schema coverage, the description compensates by explaining key parameters: 'summary default' and 'opaque cursors' clarify view and cursor; 'require explicit opt-in' clarifies includeGeometry/includeSourceCode. However, it does not explain topologyMode or limit, leaving some parameters underspecified.

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?

Title and description clearly state the tool's purpose: to analyze a CRUMB design semantically. Description specifies what it recognizes (version-pinned component parameters, terminal attachments, inferred connection groups), and this distinguishes it from sibling tools like crumb_inspect_design (raw inspection) and crumb_validate_design (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 description implies when this tool is useful (semantic analysis of component parameters, connections) but does not explicitly state when to use it over alternatives or when not to use it. No exclusions or alternative references are provided, so usage guidance is only implicit.

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

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

Annotations already declare read-only, idempotent behavior. The description adds useful behavioral details about grouping logic, exclusion of state values from part identity, and visibility of unknown components, going beyond the structured annotations without contradicting them.

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

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

The description is two sentences long, front-loads the core behavior, and contains no filler or redundant information. Every phrase adds value.

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

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

The main behavior and edge cases (excluded state values, unknown components) are well covered, and the output schema handles return values. However, the lack of parameter semantics for 'limit' and 'expectedProjectDigest' leaves some gaps in full self-sufficiency.

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 only 33%, with only 'path' having a description in the schema. The description does not explain 'limit' or 'expectedProjectDigest', and does little to compensate for the missing parameter semantics beyond implying the core grouping behavior.

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 groups components by kind and decoded part values into quantities, using a specific verb and resource. It also distinguishes this tool from siblings by describing the special handling of state values and unknown components.

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 (to get a bill of materials) but does not explicitly state when to use it versus alternatives, nor does it mention any exclusions. It provides clear context but lacks explicit alternative guidance.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds meaningful context: findings include evidence confidence and rule basis, and a rule violation returns ok=true with data.valid=false. This clarifies the non-boolean success semantics and result structure, going beyond what annotations convey.

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

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

The description is two sentences, front-loaded with the action ('Lints the inferred netlist'), and efficiently lists check categories without redundancy. Every sentence contributes meaningful 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?

Core purpose and result behavior are covered, and an output schema exists so return details are not needed. However, the impact of key parameters (topologyMode, applySwitchStates) on the checks is not explained, leaving some ambiguity for correct invocation. Adequate but not fully complete for a tool with multiple optional parameters.

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 only 25% (only 'path' has a description). The description does not mention any of the parameters, leaving topologyMode, applySwitchStates, and expectedProjectDigest unexplained. With such low schema coverage, the description should compensate, but it does not add parameter context.

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

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

The description clearly states the tool 'lints the inferred netlist' and enumerates specific electrical rule checks (supply shorts, LEDs across rails, etc.), making its function concrete. This distinguishes it from sibling tools like crumb_analyze_design or crumb_validate_design by focusing on electrical rule verification.

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

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

The description implies use for electrical rule checking of a netlist, but does not explicitly state when to prefer this over other crumb tools (e.g., crumb_validate_design for general validation or crumb_analyze_design for analysis). No exclusions or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral context: GUID-matched comparison, specific difference categories (exact bytes, modeled equivalence, root changes, component changes, unverified payload signatures), and explicit exclusions. This goes beyond what annotations provide and sets clear output constraints. No contradiction.

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

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

The description is two sentences, front-loaded with the core action and scope ('Read-only, GUID-matched comparison'), and the second sentence efficiently enumerates what it distinguishes and what it omits. Every word adds value.

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

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

The description gives a strong overview of the tool's behavior and output boundaries, and an output schema is present so return values are documented elsewhere. However, given the tool has 10 parameters and 60% lack schema descriptions, a brief mention of view modes, pagination, or topology options would improve completeness, but the provided overview is still adequate for basic understanding.

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

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

The schema has only 40% parameter description coverage (baselinePath, candidatePath, expectedBaselineDigest, expectedCandidateDigest). The tool description does not explain any parameter semantics, leaving view, limit, cursor, topologyMode, includeGeometry, and compatibilityProfile without contextual guidance. Given the low schema coverage, the description was expected to compensate but does not mention any 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 specifies a comparison tool ('Compare CRUMB files') with a particular scope: baseline vs candidate .cru under crumb.unity/1.3.5. It lists specific output categories (exact bytes, modeled equivalence, root/component changes, payload signatures) that distinguish it from sibling tools like crumb_inspect_design or crumb_validate_design.

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

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

The description gives clear context: use for read-only, GUID-matched comparison of two CRUMB design files under a specific compatibility profile. It does not explicitly name alternatives or state when not to use it, but the purpose is unambiguous and the exclusions (no raw XML, firmware, EEPROM, thumbnails) help set expectations.

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

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

Annotations already disclose readOnlyHint=true and idempotentHint=true, covering safety and side-effect profile. The description adds context like 'version-pinned' and 'machine-readable evidence vocabulary,' which gives useful extra detail about the response. However, it does not describe pagination, output size limits, or any potential error conditions, though with an output schema present, this is less critical.

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

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

The description is a single, dense sentence that packs all necessary information without redundancy. It is front-loaded with the action ('Returns') and lists the content items in a structured, comma-separated manner. Every phrase contributes value, making it both concise and complete.

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

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

With an output schema present, return values are already defined, so the description need not detail them. The tool is read-only, has one optional parameter, and the description covers its primary behavior and filtering ability. The main gap is the absence of usage guidance, but that is scored separately. Overall, the description is sufficiently complete for an agent to understand and call the 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 only defines toolId as an integer with min/max. The description says 'Optionally filter by toolId,' which adds meaning that this parameter filters the returned catalog. Yet it does not clarify what a toolId represents (e.g., which catalog IDs are valid, whether it aligns with component schema IDs) or how filtering behaves (exact match, partial). Given 0% schema description coverage, a bit more detail would be helpful.

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 'Returns' and clearly specifies the resource: 'version-pinned CRUMB tool-ID catalog, payload signatures, typed parameters, terminal labels, confidence values, and their machine-readable evidence vocabulary.' This is a specific verb+resource that distinguishes it from sibling tools like crumb_get_component (which likely fetches a single component) and crumb_ic_reference (which likely references datasheets). The optional filter by toolId further clarifies scope.

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

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

The description provides no when-to-use guidance, exclusions, or alternatives. It only mentions 'Optionally filter by toolId,' which is a parameter usage detail, not a high-level usage guideline. Without context on when to choose this catalog over related tools (e.g., crumb_get_component), an agent lacks direction.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: it collapses jumper wires, infers VCC/GND names from DC supply terminals, supports optional switch-state merges, and explicitly mentions provenance/confidence. These details go beyond the annotations and clarify what the operation does.

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 main purpose, and each clause adds meaningful detail. No filler or redundant repetition of schema info.

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

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

An output schema exists, so return values are already covered. However, the description lacks explanation for topologyMode and expectedProjectDigest parameters and gives no explicit usage guidance. It covers the core behavior but leaves important context gaps for full agent decision-making.

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 only 33% (path and applySwitchStates have descriptions). The description adds meanings for 'paged' (limit/cursor) and 'saved-switch-state merges' (applySwitchStates), but leaves topologyMode enum values and expectedProjectDigest completely unexplained. The description only partially compensates for the schema gap.

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

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

The description clearly states the tool 'returns paged electrical nets' after collapsing jumper wires, and the title says 'Export named electrical nets'. It distinguishes from sibling tools like logisim_export_netlist by mentioning crumb-specific behaviors such as VCC/GND name inference and saved-switch-state merges.

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

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

No explicit when-to-use or alternative tools are mentioned. The description implies usage for netlist export with jumper collapse and optional switch-state merging, but does not say when to prefer this over siblings like crumb_trace_net or logisim_export_netlist. Usage context is only implied.

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 non-overwrite behavior, which is a meaningful safety trait beyond the annotations. It also clearly states that raw XML is only returned when includeXml=true, providing return-behavior transparency. Since annotations already cover read-only/destructive hints, this additional detail is valuable but not exhaustive.

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 purpose and immediately followed by parameter guidance. Every sentence contributes meaning without redundancy, matching the conciseness of high-quality tool descriptions.

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

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

Given the presence of an output schema and annotations, the description focuses on the essential generation behavior: creating a known fixture, writing to a file, or returning XML. It fully explains the primary output modes and the no-overwrite guarantee. It could be more explicit about what happens if neither outputPath nor includeXml is provided, but the output schema likely covers return values.

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

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

With schema description coverage at 0%, the description must compensate. It does explain the role of outputPath (file artifact) and includeXml (raw XML return), but it leaves name and kind to schema naming and enum values. This partial explanation is helpful but does not fully cover all parameters.

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

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

The description 'Creates one known fixture without overwriting' clearly states the specific action (create), resource (fixture), and scope (one known kind). It distinguishes from sibling tools like crumb_inspect_design and crumb_validate_design, which read or validate rather than generate.

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 how to use the tool: 'Provide outputPath for a file artifact; raw XML is returned only when includeXml=true.' This gives practical invocation guidance, but it does not explicitly mention when to choose this tool over alternatives or list excluded use cases. The unique generation purpose is implied by the name, but not stated as a rule.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds valuable context: windowed access to firmware source (pagination via sourceOffset), the concept of an 'analyze cap,' and inferred connection groups—behaviors not visible in annotations. This enriches the agent's understanding without contradiction.

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

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

Two compact sentences deliver the core purpose and key differentiator without redundancy. The first sentence lists the return contents, the second positions it for iterative workflows. 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?

With an output schema present, the description need not detail return fields. It covers the tool's purpose, the main resource, and a distinctive behavior (windowed source access). It does not explain topologyMode or expectedProjectDigest, but for a read-only companion with strong annotations and output schema, the context is adequate.

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 57%, covering path, componentId, sourceOffset, and expectedProjectDigest. The description adds meaning to includeGeometry and includeSourceCode by mentioning geometry and source code, and 'past the analyze cap' relates to sourceOffset. However, topologyMode is left unexplained, and the description does not elaborate on all parameter interactions, so it partially compensates.

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

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

The description opens with a specific verb ('Returns') and identifies the exact resource ('a single component by id') and its contents (parameters, terminals, geometry, connection groups, firmware source). It also positions itself as 'read-back companion' for iterative work, clearly distinguishing it from sibling tools that analyze or list components.

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 'read-back companion for iterative work on one part' implies when to use this tool (when focusing on a single component), and the mention of 'past the analyze cap' hints at an alternative (crumb_analyze_design) that has a cap. However, it does not explicitly name alternatives or state exclusions, 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 context beyond the annotations: it notes the registry is 'version-pinned' (reproducible), pin names are 'ordered', and 'explicit unresolved pins' are returned, which is a valuable edge-case disclosure. These complement the readOnlyHint and idempotentHint annotations rather than contradict them. The example query also gives a concrete feel for behavior, though it stops short of describing error handling or interaction of both params.

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 core action, and includes an illustrative example. Each sentence adds distinct value: the first explains the query modes and registry pinning, the second details the return fields. There is no extraneous text 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?

For a read-only lookup tool with two optional parameters and an output schema, the description covers the essential usage: query modes, example, and return structure. The version-pinning note adds reproducibility context. Missing are explicit alternatives/usage boundaries and error/edge-case handling (e.g., no matches, both params given), but these are secondary given the annotations and 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 only 50% (query has a description, prefabId does not). The description compensates by explaining both parameters: query is matched as a 'label/package substring' and prefabId is the alternative lookup mode. It also provides a concrete example ('74HC138') that clarifies the substring semantics. However, it does not specify what happens when both parameters are provided, how prefabId is formed, or precedence between them, leaving some 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 specifies the verb 'Queries', the resource 'version-pinned tool-5 IC registry', and the exact inputs (prefabId or label/package substring) and outputs (package labels, ordered pin names, explicit unresolved pins). It clearly states what the tool does without being tautological. However, it does not explicitly differentiate from sibling tools like crumb_get_component or crumb_component_catalog, which may also retrieve component data.

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

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

The intended use is implied by the title and description (looking up IC packages/pinouts), and the query modes are stated. However, there is no explicit when-to-use vs. alternatives, no mention of preferred scenarios, and no explanation of edge cases like multiple matches or empty results. 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds behavioral context beyond annotations: it states the output is 'bounded' and consists of a save summary and tool-ID counts, and that it is not for paginated semantic details. This helps the agent form accurate expectations about scope and granularity.

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

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

Two sentences, front-loaded with the tool's purpose and followed by a pointer to the sibling tool. Every word earns its place; no filler or repetition of schema/annotations.

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

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

Given the tool has an output schema, annotations, and only two well-documented parameters, the description is complete enough to guide selection and invocation. It communicates the compact, bounded nature and the existence of a more detailed alternative, making it fully contextual for an agent.

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

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

Schema description coverage is 100% (both 'path' and 'expectedProjectDigest' have clear descriptions). The tool description does not add parameter-level semantics, but that's acceptable given the schema carries the full burden. 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 tool returns 'a bounded save summary and tool-ID counts', identifying the specific resource and output type. It also distinguishes itself from the sibling crumb_analyze_design, which provides paginated semantic details, eliminating ambiguity.

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

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

Explicitly directs the agent to use crumb_analyze_design for paginated semantic component and connection details, effectively conveying when this compact inspection tool is appropriate. This is a clear when-to-use vs. alternative guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds behavioral context by specifying the return metadata (size, modification time, SHA-256 digest) and the root/subdirectory scoping. It does not contradict annotations and goes beyond what the structured hints 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?

A single well-structured sentence communicates the action, scope, and purpose without any fluff or repetition. Every element is meaningful and front-loaded.

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

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

Given that an output schema exists, return values are already documented. Annotations cover safety, and the description provides the core purpose and typical scope. Minor gap: the phrase 'or one subdirectory' is slightly ambiguous regarding recursion default, but the tool is otherwise adequately described for its 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?

Schema description coverage is only 25% (only 'dir' has a description), and the tool description fails to meaningfully explain the remaining parameters. It mentions digest inclusion and subdirectory traversal in passing but does not clarify 'limit', 'recursive', or 'includeDigests' semantics, leaving the agent with incomplete parameter understanding.

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

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

The description uses a specific verb ('Enumerates') and identifies the resource ('.cru files' representing CRUMB projects) and scope ('under the workspace root or one subdirectory'), clearly distinguishing it from sibling tools like crumb_inspect_design or crumb_analyze_design. The title reinforces the purpose.

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

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

The description states when to use this tool: 'so a model can discover projects without being handed a path.' This implies discovery/listing context and is distinct from siblings that inspect, analyze, or validate designs. However, it does not explicitly exclude alternatives or mention 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?

Annotations already declare readOnly and idempotent hints, and the description adds valuable behavioral context: determinism, pagination, and provenance details ('structured attachment, board, jumper, and optional saved-switch provenance'). It also clarifies that it is static connectivity inference, not simulation, which goes beyond the annotations.

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

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

The description is two concise sentences with the main action front-loaded. No unnecessary words or repetition, and it packs in key differentiators and behavioral notes.

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

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

Given the tool's complexity (9 params) and the presence of an output schema, the description provides sufficient context about the tool's purpose, determinism, pagination, and provenance. It doesn't detail return fields (not needed) and is concise, though it could slightly expand on usage conditions.

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

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

Schema coverage is 56%, leaving parameters like limit, cursor, and expectedProjectDigest undocumented. The description mentions 'stable index' and 'paged' and 'saved-switch' which partially maps to terminalIndex, limit/cursor, and applySwitchStates, but it doesn't fully compensate for the missing parameter explanations in the schema.

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

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

The description clearly states the action ('Selects one component terminal by stable index') and the resource (a connectivity witness), with specific detail about what is returned. It also distinguishes itself from siblings by noting it is 'not current flow, path enumeration, or simulation,' which is precise and differentiates it from other 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 provides context on the tool's static conductive inference and explicitly excludes other analysis types, giving implicit guidance on when not to use it. However, it doesn't name specific alternative tools or provide explicit 'use this when' scenarios, 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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description adds critical behavioral detail: it does not launch the game, and it describes the return semantics for a bad design ('ok=true and data.valid=false'). This gives the agent insight into what to expect from the tool's execution, beyond what annotations alone 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 two sentences, front-loaded with the core purpose, and every phrase earns its place. No redundancy or filler. It efficiently conveys the tool's function, key constraint, and a notable output behavior.

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

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

Given the output schema exists and annotations are present, the description is complete. It states the tool performs validation, does not launch the game, and clarifies the return behavior for invalid designs. The tool's complexity is low, and nothing essential is missing for an agent to select and invoke it correctly.

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

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

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no additional meaning about the parameters themselves; it focuses on the tool's overall behavior. The mention of return values is output-related, not parameter-related.

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: 'Performs XML and CRUMB structural checks without launching the game.' This identifies a specific verb (performs checks) and resource (CRUMB design), and distinguishes it from siblings like crumb_analyze_design or crumb_inspect_design by emphasizing no game launch. 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 provides clear context for when to use this tool: when you need XML/structural validation without launching the game. However, it does not explicitly name alternative tools or state when not to use it. The 'without launching the game' context is a strong differentiator but lacks explicit exclusions or sibling comparisons.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable context by mentioning 'truthful limitations' and 'recommended workflows.' This goes beyond the annotations and reassures that the tool provides honest constraints and guidance. No contradiction with annotations.

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

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

The description is a single, well-structured sentence that front-loads the key fact ('Zero-argument onboarding') and then lists contents. It is efficient with no wasted words.

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

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

For a zero-parameter onboarding tool with an output schema, the description covers the essential content areas (conventions, backends, limitations, workflows). It fully describes the tool's scope without needing to document parameters or return values, and the output schema covers specific return structure.

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 for parameter semantics is 4. The description reinforces that it's zero-argument but adds no additional parameter meaning, which is unnecessary given no parameters 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 is for orientation/onboarding to Circuitarium MCP, listing specific content areas (conventions, backends, limitations, workflows). It uses a specific verb ('orient') and is distinguishable from sibling tools which perform specific design/logic operations rather than meta-level overview.

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 guidance is given: 'Call this first when unsure.' This establishes when to use the tool and implies that if you know what you're doing, you can skip it. It also clarifies that it's a zero-argument first step, which is direct and actionable.

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 substantial behavioral constraints beyond the annotations: deterministic, simulator-neutral, bounded evidence, no file reads, no tool execution, no receipt authentication, and never certifies physical hardware. These details are not present in the annotations and significantly enhance the agent's understanding of the tool's capabilities and limitations.

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 dense sentences: the first states the core purpose, the second lists critical constraints. Every phrase contributes value (e.g., 'deterministic,' 'simulator-neutral,' 'bounded,' 'reads no files'), with no redundant or filler 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 highly complex tool with a rich schema and annotations, the description captures the essential nature and key constraints. It does not detail all parameters or return values, but the extensive input schema and output schema (present in the context) fill in those gaps, making it sufficient for initial tool selection.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'explicit claims' and 'bounded caller-reported evidence,' giving some meaning to the claims and evidence parameters, but it says nothing about the target or declaredInterface parameters. Given the complexity of the schema, this partial coverage is insufficient.

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 language: 'Builds a deterministic, simulator-neutral plan for explicit claims using bounded caller-reported evidence.' It clearly identifies the action (building a plan) and the object (explicit claims), and differentiates from sibling validation tools by stating it reads no files and runs no tools or simulators.

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 that this tool is for planning, not execution, by explicitly stating 'It reads no files, runs no tools or simulators.' This implies when to use it versus actual validation tools, but it does not name specific alternatives or provide an explicit when-not-to-use condition.

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

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

The description adds meaningful behavioral detail beyond the annotations: it specifies that invalid input returns 'ok=true and data.valid=false with diagnostics.' This discloses a key aspect of the tool's behavior (validation outcome for invalid input). Annotations already signal read-only, idempotent, and closed-world behavior, and the description does not contradict them. Slightly more context on valid output could be included, but the provided detail is useful.

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

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

The description is concise, with two sentences that front-load the core purpose and then mention the invalid-input behavior. No wasted words or redundancy, and the structure is clear: function, scope, and outcome for a key case.

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

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

Given the tool's complexity (validation against multiple contract facets), the description captures the essential purpose and a notable edge case. Since an output schema exists, it can document return values, and the description does not need to explain them. The lack of context about the exact contract format is a minor gap, but the description is adequate for a validation tool with moderate complexity.

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

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

The schema description coverage is 0%, so the description must compensate. However, it only says 'arbitrary JSON value' and does not elaborate on the expected structure of the 'experiment' parameter. The contract types (circuit, firmware, probe, assertion, timing) are mentioned but not connected to how the JSON should be organized. The schema itself only defines a generic JSON type, so the description adds little practical meaning for constructing a valid input.

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: it validates an arbitrary JSON value against a 'simulator-neutral circuit, firmware, probe, assertion, and timing contract.' The verb 'Checks' is specific, the resource is 'experiment,' and the scope (contract validation) distinguishes it from sibling tools focused on design inspection or analysis.

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 explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It does not mention that this is for experiments specifically, nor does it reference sibling tools like crumb_validate_design. The agent must infer usage solely from the tool name and the phrase 'portable electronics experiment,' which is minimal guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds important limitations: 'bounded' parsing and a caveat that static parsing is not simulation evidence. It also mentions 'explicit conversion-loss summaries,' signaling potential data-loss reporting. This adds meaningful context beyond the annotations without contradicting them.

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

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

The description is two sentences with no filler. The first sentence front-loads the core action and deliverables; the second adds a critical caveat. 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?

Given the presence of an output schema, read-only and idempotent annotations, and a concise description with a key limitation warning, the description is complete for a static analysis tool. It conveys the scope (bounded XML), the domain (Logisim-evolution), and the non-simulation nature without needing to enumerate return fields.

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

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

The input schema has 100% coverage, describing all three parameters (path, circuit, expectedProjectDigest) with clear types and descriptions. The tool description does not add parameter-specific details beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb ('Parses') and resource ('bounded .circ XML') and enumerates the output artifacts (project, circuit, pin, clock, component, conversion-loss summaries). It effectively distinguishes itself from sibling tools like crumb_analyze_design via the .circ format and from logisim_export_netlist or logisim_truth_table by focusing on summary parsing.

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 an explicit when-not: 'Static parsing is not simulation evidence.' This warns against using the tool when simulation behavior is required. It does not name a specific alternative like logisim_run_test_vector, but the exclusion is clear and actionable. The purpose of static analysis is implied, so it earns 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?

The description discloses an external dependency ('separately installed JAR'), a version precondition ('after it self-reports Logisim-evolution 4.1.0'), and a limitation ('Success proves that configured process loaded the staged project, not behavioral simulation or binary authenticity'). This adds value beyond annotations, which only indicate idempotent and non-destructive behavior.

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

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

The description is only two sentences and not verbose, but it is not well-structured: the primary purpose is in the title, and the first sentence leads with the invocation mechanism rather than the intended outcome. Some phrasing is cryptic ('--tty stats', 'staged project').

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

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

The output schema and annotations provide some coverage, but the description lacks usage context, does not explain what 'stats' includes, and does not address the external JAR prerequisite or installation. It also fails to position the tool among siblings, making it incomplete for effective selection and invocation.

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

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

The description adds no parameter information. The schema covers 3 of 5 params with descriptions (path, circuit, expectedProjectDigest), but limit and timeoutMs are undocumented. The description does not compensate for the missing coverage or clarify parameter usage.

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 title clearly states 'Load a project and count Logisim components', and the description adds invocation details ('Invokes the separately installed JAR... with --tty stats'). However, the description focuses on the mechanism rather than explicitly stating the counting purpose, and it does not distinguish from sibling tools like logisim_analyze_design.

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 explicit guidance on when to use this tool versus alternatives. The caveat 'not behavioral simulation or binary authenticity' is a clarification, not a usage directive. No alternative tools 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral traits: 'coordinate-endpoint nets with explicit loss markers' and the explicit non-inference of geometry/junctions/behavior. This goes beyond the annotations and gives the user a clear picture of what the output will and won't contain. No contradiction with annotations.

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

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

Two concise sentences with no fluff. The first sentence states the action and the second clarifies limitations. Information is front-loaded, and every word earns its place. Perfectly 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?

With an output schema present, the description needn't detail return values. It covers the core semantics (coordinate-endpoint nets, loss markers, non-inference) and limitations. It could elaborate on pagination behavior or the purpose of expectedProjectDigest, but these are either inferable or present in the schema. Given the tool's moderate complexity, the description is nearly complete but not exhaustive.

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 60%, covering path, circuit, and expectedProjectDigest, but limit and cursor lack descriptions. The tool description adds no parameter-specific details, so it doesn't compensate for the gaps. However, the parameter names (limit, cursor) are self-explanatory, and the title's 'partial' hints at pagination. The schema plus implicit naming provide a baseline understanding, so a 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 exports simulator-neutral coordinate-endpoint nets with loss markers, which is a specific verb+resource. It also distinguishes itself by noting what it does not infer (gate geometry, mid-segment junctions, behavior), giving it a defined scope beyond a generic export. However, it doesn't explicitly name sibling alternatives, so it falls short of a 5.

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

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

The description implies usage through its limitations: 'does not infer unmodeled gate geometry, mid-segment junctions, or behavior' tells the user this is for partial netlists only. It provides useful context but does not explicitly say when to use this tool versus alternatives like crumb_export_netlist, nor does it state exclusions. This is adequate but lacks clear guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context by clarifying that no Logisim launch occurs and that digests are raw-byte based, which helps set expectations. No contradiction with annotations.

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

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

Two succinct sentences front-load the main purpose and end with a clarifying note. Every word earns its place, with no fluff.

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

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

The tool is simple (list projects) and the presence of an output schema covers return value details. The description covers key behavioral aspects (static, no launch, digest computation) that are not in annotations. Minor gap: 'stable raw-byte digests' is not expanded, but that is acceptable given the 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 only 33% (only 'dir' has a description); 'limit' and 'recursive' are left to the schema's type/defaults. The description does not explain any parameter semantics, such as how 'dir' is resolved or how 'recursive' affects discovery. Since the description fails to compensate for the low schema coverage, this dimension is weak.

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 'Discovers' with a clear resource: 'workspace .circ projects'. It adds a distinctive detail ('stable raw-byte digests') and explicitly contrasts with launching Logisim, separating it from sibling tools like logisim_analyze_design.

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's static file discovery and does not launch Logisim, implying use when you need to list projects without executing the application. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full usage guidance.

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

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

The description discloses that the tool uses staged snapshots (non-destructive), requires a self-reporting JAR version, and specifies how assertion failures are represented in the return value. These details go beyond the annotations, which already state idempotence and non-destructiveness.

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

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

The description is a long, winding sentence that starts with implementation details rather than the core action, followed by a short sentence about failures. It could be more front-loaded and concise, but it is not excessively verbose.

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 output schema exists and annotations cover safety, the description is somewhat complete but misses the overall purpose and does not describe success behavior or preconditions. With 7 parameters and no parameter semantics, it leaves a notable gap in 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 schema covers only 57% of parameter descriptions, leaving timeoutMs, maxFailures, and expectedVectorDigest undocumented. The description adds little beyond vague references to the project and vector file, failing to explain the purpose or constraints of these parameters.

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

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

The description clearly indicates the tool runs a test vector against a Logisim project, referencing the project and .vec/.txt file. It distinguishes from sibling tools by focusing on test vector execution, though it buries the main verb in implementation detail about the JAR.

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 explicit guidance on when to use this tool versus alternatives like logisim_analyze_design or logisim_truth_table. Usage is only implied by the name and the mention of test vectors, with no mention of scenarios 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?

The description discloses that an external JAR is invoked and that a version self-report is checked, which is beyond the annotations. However, it does not mention potential side effects, failure modes, or the requirement for the JAR to be installed, leaving significant behavioral 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 a single dense sentence with no fluff, but it packs multiple clauses (JAR invocation, version check, mode, bounding) into a somewhat convoluted structure. It is reasonably concise but could be clearer with segmentation.

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 6-parameter schema and external dependency, the description is insufficient. It does not mention prerequisites like the JAR installation, output details, or parameter semantics. The output schema exists but does not cover the operational context needed for 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 description coverage is only 50%, and the description does not compensate by explaining the undocumented parameters. It indirectly references input width bounding via 'statically bounding declared input width' but fails to clarify limit, timeoutMs, or maxInputBits 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 clearly states it simulates a Logisim truth table via JAR invocation, and the title reinforces this. The mention of CSV/binary table mode distinguishes it from sibling tools like logisim_analyze_design. However, the description is unnecessarily technical and focuses on implementation details rather than the user-facing function.

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

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

No guidance is provided on when to use this tool versus alternatives such as logisim_run_test_vector or logisim_analyze_design. The description lacks context for tool selection, leaving the agent to infer applicability from the tool name alone.

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