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

No annotations are provided, so the description must disclose behavioral traits such as whether the tool is read-only, what it returns, or any side effects. It only states what the contract covers, not how the tool behaves. The reference nature is implied but not explicitly disclosed.

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 leads with the core purpose ('complete virtual-device authoring contract') and then lists concrete covered topics. Every phrase adds information, and there is no fluff 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?

The tool has no output schema and no annotations, so the description should explain what the tool returns or how it behaves when invoked. It does thoroughly describe the scope of content, but falls short on return behavior and usage 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 tool has zero parameters, and the baseline for zero parameters is 4. The description does not need to add parameter-specific meaning since there are no inputs to explain.

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 identifies the tool as the complete virtual-device authoring contract for devices/*.rhai and enumerates the covered aspects (meta(), pin/terminal modes, behavior handlers, framebuffer/display API, execution model). This distinguishes it from more specific sibling tools like ide_device_template or ide_device_script. However, it lacks an explicit action verb such as 'retrieve' or 'view,' so it reads more like a definition than a tool instruction.

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 'authoring contract' implies this tool is used when working with virtual-device scripts, but it never explicitly states when to use it versus alternatives like ide_device_template or ide_device_script. No exclusions or alternative guidance are given.

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

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

With no annotations, the description carries the burden. It discloses the return fields and filter behavior, and contrasts with ide_device_script, clarifying that this tool only lists models. It does not mention error conditions or side effects, but as a listing tool, 'List' implies a read-only operation, making this adequate.

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 highly concise, with two sentences front-loading the core purpose and then providing filter details and a pointer to a sibling tool. Every sentence adds value with no redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the purpose, return fields, filter options, and how to access source code. It is contextually complete and appropriately scoped for an agent to invoke correctly.

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

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

Schema coverage is 0%, so the description must compensate. It adds meaning to the 'filter' parameter by defining matching semantics (name or bus) and enumerating valid bus values. It does not specify exact filter syntax, but for a simple optional filter this is sufficient.

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

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

The description clearly states the tool lists virtual-device models with specific attributes (name, bus, address, display, pins, purpose). It distinguishes itself from sibling tools like ide_device_script by explicitly pointing to that tool for reading source, making the purpose unambiguous.

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

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

It describes the optional filter matching name or bus with valid bus values (none/uart/spi/i2c), giving concrete usage guidance. It also mentions ide_device_script as an alternative for reading source, though it does not explicitly state when not 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?

No annotations are provided, so the description carries the full burden. It does disclose that it returns full Rhai source and that models are shipped/built-in, which gives some behavioral context. However, it doesn't mention error handling for invalid names, the format of the response, or any permissions/rate limits. For a simple read tool this is acceptable but not rich.

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 primary action and includes examples and purpose. Every word earns its place; no fluff 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 tool with one parameter and no output schema, the description conveys the core function, sample values, and intended use. It lacks details like what happens for unknown names or a pointer to a list of shipped models, but the overall context is sufficient for an agent to select and invoke it.

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 provides only the parameter name and type with 0% description coverage. The description adds meaning by giving three concrete examples of valid values ('ssd1306', 'max7219', 'led'), which helps the agent understand the expected input. It doesn't fully define the value space but compensates significantly.

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

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

The description uses a specific verb and resource: 'Return the full Rhai source of a shipped device model' with concrete examples ('ssd1306', 'max7219', 'led'). It clearly distinguishes itself from sibling tools like ik_device_info or ide_device_template by focusing on returning source code as a reference.

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 need a worked reference for authoring your own device model. It doesn't explicitly exclude alternatives, but the 'worked reference' phrasing sets expectations. With many sibling device tools, an explicit alternative mention would be stronger, so not a 5.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only gives a noun phrase and does not explain what the tool does operationally—whether it returns a file, prints a template, or requires any action. There is no mention of return format, side effects, or 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 a single short sentence/fragment that is front-loaded and wastes no words. However, it is slightly under-specified in terms of full sentence structure, but for the information provided, it is 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?

With no annotations, no output schema, and zero parameters, the description is the only context. It mentions the language (.rhai) and purpose (virtual-device script starter), but lacks details like how the template is accessed, what the user is expected to do with it, or any related commands. This is insufficient for a complete 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 tool has zero parameters, making parameter documentation unnecessary. The schema is trivially complete (100% coverage for a properties object with no properties). The baseline for 0 params is 4, and no param semantics are missing.

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 identifies a specific resource: a starter devices/*.rhai virtual-device script. It conveys that the tool provides a template to adapt for device scripts, which is clear even without a strong verb. It is distinguishable from sibling tools like ide_device_script or ide_examples because it explicitly mentions 'starter' and 'adapt'.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The phrase 'to adapt' implies it is a starting point for creating a device script, but it does not state conditions, prerequisites, or contrast with other IDE tools. Users are left to infer use cases.

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

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

With no annotations provided, the description carries the full burden. It discloses the exact file set returned and implies a read-only operation via 'Return.' It does not explain error behavior for invalid names, but for a simple retrieval tool the provided detail is solid.

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

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

The description is a single sentence that front-loads the core action and then provides concrete detail in parentheses. 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 tool with one parameter, no output schema, and no annotations, the description covers the essential behavior: what is returned and the structure of the example project. It lacks edge-case information like not-found handling, but overall it is sufficiently complete for an agent to invoke it correctly.

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

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

The schema has one required string parameter 'name' with no description. The tool description implies that 'name' identifies the example project, which is essential context. However, it does not specify allowed name formats or give examples, so it provides only partial compensation for the 0% 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 uses a specific verb ('Return') and clearly defines the resource ('all files of one example project'), listing exact file patterns (main.ik, tests/*.rhai, devices/*.rhai, info.json, README). It distinguishes itself from siblings like ide_examples by emphasizing 'one example project' versus a list.

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

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

The description implies usage: when you need all files of a specific example project. It also frames the tool as a 'complete worked reference,' which suggests a learning/reference context. However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden. It transparently indicates a read-only operation via the verb 'List' and adds useful context about the example structure ('program + wiring + often tests/devices') and returned fields ('title and description'). This goes beyond a minimal statement, though it does not address edge cases like pagination or sorting.

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 is front-loaded with the action and resource. The parenthetical clarification adds valuable information without bloat, and every word contributes meaning. It is an example of efficient writing.

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 list tool with no annotations, no output schema, and no parameters, the description is complete. It specifies the scope ('IDE's bundled'), the content of examples, and the returned fields ('title and description'), giving an agent all needed information to select and invoke the tool correctly.

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

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

The tool has zero parameters, so the empty schema fully covers all inputs. Per the calibration baseline, a parameterless tool receives a 4. The description adds no unnecessary parameter complexity and is sufficient.

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

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

The description clearly uses the verb 'List' and identifies the specific resource: the IDE's bundled breadboard example projects. It also clarifies what these projects contain (program + wiring + often tests/devices), making the tool's purpose unambiguous and distinguishing it from sibling examples like ik_examples.

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 this tool is for viewing bundled examples but provides no explicit guidance on when to use it over alternatives such as ide_example or ik_examples. There is no mention of exclusions or specific scenarios, though the phrase 'IDE's bundled' gives some context.

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

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

With no annotations provided, the description carries the burden. It describes the content of the overview (program, tests, devices) but does not disclose behavioral traits such as whether it returns a simple reference or an interactive guide. This is adequate for a documentation tool, but not rich.

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?

One concise sentence front-loads the purpose and ends with a strong directive. No wasted words; every phrase 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 reference/overview tool with no parameters or output schema, the description sufficiently covers what the tool contains and when to use it. It does not explain the format of the overview, but that is not critical for this tool type.

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

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

The tool has zero parameters, and the schema is empty. Per the baseline rule for 0 params, a score of 4 is appropriate; the description adds no parameter information because none is needed.

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 what the tool does: it explains how to build a complete ikide project covering program, tests, and devices, and how they fit together. This specific verb+resource distinguishes it from siblings like ik_overview or ik_tutorial.

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

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

It explicitly says 'READ THIS before writing tests or devices,' giving clear when-to-use guidance. It does not mention alternatives or when-not-to-use, which prevents a 5.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does mention 'headless' operation and 'throwaway workspace', which is useful. However, it does not describe side effects, return format details, or failure behavior, leaving some 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 three sentences long, front-loaded with the main purpose, and every sentence adds value. The two-mode usage is clearly and economically stated.

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

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

Given the tool has 7 parameters and no output schema, the description covers the main modes and optional parameters well. It does not detail every default (e.g., test_name, program_name), but the schema already covers those. The essential usage context is complete enough for a test-running 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?

Schema coverage is high (86%), and the description adds semantic grouping (workspace OR program+test) and clarifies that mcu is for 'load_hex tests'. This goes beyond the schema field descriptions, which individually list the parameters but not the relationship between 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 uses a specific verb 'Run' with a clear resource ('headless `ikide test` runner') and a specific outcome ('return the real PASS/FAIL verdict'). It clearly distinguishes itself from sibling tools like `ik_simulate` or `ik_check` by focusing on the test runner.

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 two usage modes: providing an existing workspace or inline program+test. It also mentions optional devices and mcu. However, it does not explicitly exclude alternatives or name when not to use the tool, so it falls short of a 5.

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

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

With no annotations, the description must carry the transparency burden. 'Full-text search' implies a read-only operation, but the description adds no details on result format, pagination, matching behavior, or potential limitations. It provides basic scope but no deeper behavioral context.

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

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

The description is a single sentence that is concise, front-loaded, and avoids redundancy. Every word contributes to the purpose.

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

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

The tool is simple with only two parameters, and the description adequately covers the search scope. However, without parameter explanations or any note on result format, the description is not fully complete for invocation. It meets the minimum viability but has clear gaps.

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

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

The input schema has zero description coverage for its parameters, and the description itself does not mention 'query' or 'max_results'. The agent only sees types and a default, with no explanation of what the query should contain or how max_results controls results. The description fails to compensate 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 performs 'full-text search' across specific resources (IDE device scripts, device-authoring guide, example projects). This verb+resource combo distinguishes it from sibling tools like ik_search, which likely targets language reference, and ide_examples, which may list examples.

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 context on what content is searched, so an agent can infer when to use this tool. However, it does not mention when not to use it or explicitly reference alternative tools, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden. It conveys that the tool is diagnostic and lists specific information it checks, implying a read-only operation. However, it does not explicitly state side effects, error behavior, or whether any system state changes occur. The term 'Diagnostics' provides a hint but leaves room for interpretation.

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, front-loaded with 'Diagnostics' and listing exactly what is resolved. There is no waste or redundancy, making it easy to quickly understand the tool's function.

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 partially fulfills the need by listing three diagnostic items. However, it does not explain the format of the output, how to interpret 'available', or provide background on 'ikide'. These gaps leave the tool somewhat underspecified 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?

The tool has zero parameters, so the schema already fully covers this aspect. The description does not need to explain parameters. The baseline for 0 params is 4, and no additional clarification is required.

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

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

The description clearly states the tool's purpose: diagnostics for resolved ikide root, binary path, and IDE checkout availability. The verb 'diagnostics' is specific and the listed items make the output clear. However, it does not explicitly differentiate from sibling tools like ide_overview or ide_test_api, though the focus on status diagnostics is distinctive.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of scenarios where ide_status is preferred over ide_overview or other ide_* tools. The description only states what it does, not when to invoke it.

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

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

No annotations are provided, so the description must disclose behavioral traits. It describes the content coverage (functions, assertions, groups) but does not clarify what the tool actually returns (e.g., a document listing, a usage guide) or whether it is read-only. The nature of a reference API implies informational output, but that is not stated.

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 long sentence that packs in many relevant details (scope, areas, assertions, grouping, notes, examples). It is dense but not bloated or redundant. Every clause contributes to the overall picture, so it earns a 4.

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 as a reference API, the description provides a broad overview but lacks specifics about the output format or how the information is presented. It does not describe pagination, searchability, or whether examples are included inline. This is adequate for a reference tool but leaves room for more completeness.

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

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

The tool has zero parameters, and the schema is an empty object, so the baseline is 4. The description does not need to explain parameters, and it adds context by outlining the API areas covered, which is sufficient.

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

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

The description clearly identifies this as the complete test-bench (Bench) API for tests/*.rhai, listing the specific areas covered (program, run, UART, SPI, etc.). This distinguishes it from sibling reference tools like ik_compiler_reference or ide_device_api, though it does not explicitly contrast with them.

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

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

The description implies usage context by mentioning 'tests/*.rhai' and 'how-to-run notes and examples', but it does not explicitly state when to prefer this tool over alternatives like ide_device_api or ide_test_template. There is no 'use this when' or 'instead of' 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. It does not disclose any side effects or behavioral traits, such as whether the tool returns a template, writes files, or is read-only. 'Starter' gives a vague hint of non-destructiveness but is not explicit.

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

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

The description is a single short sentence with no fluff or redundant information. It is appropriately concise and front-loaded, though it lacks substance. This is acceptable for conciseness, even if clarity suffers.

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 zero parameters and no output schema, the description is the only specification, yet it fails to clarify what the tool actually returns or how 'adapt' behaves. It is not sufficient for an agent to understand what the tool does or how to invoke it correctly, making the context incomplete.

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

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

The tool has zero parameters, so the input schema is trivially complete (100% coverage). With no parameters to explain, the description is not required to provide additional semantic detail, so the baseline score of 4 applies.

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

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

The description states what the tool is ('a starter tests/*.rhai bench script') but does not state a clear action (e.g., retrieve, create, list). It leaves the function ambiguous, and the name 'ide_test_template' is almost tautological with the description. No differentiation from sibling tools like ide_test_api or ide_run_tests.

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 context on when to use this tool or how it compares to alternatives. The phrase 'to adapt' hints at a purpose but does not specify scenarios or exclusions. No explicit guidance is given.

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

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

With no annotations provided, the description carries the burden of transparency. It discloses the behavior: "compile and return only ok + diagnostics (no artifact)", indicating a non-mutating, read-only operation. It also notes speed. It does not detail side effects or auth requirements, but for a check tool this is reasonable. It could explicitly state that no files are modified, but the 'no artifact' clause implies it.

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

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

The description is extremely concise: two sentences that front-load the core purpose and output, then add positioning context. Every word earns its 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?

Given no output schema and no annotations, the description provides essential context: it tells the agent the tool returns "ok + diagnostics" and produces no artifact. However, it leaves out some details such as whether path/source are mutually exclusive or any error handling semantics. For a tool with only three optional parameters, it is largely 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?

The input schema has 100% description coverage for all three parameters (path, source, target), so the baseline is 3. The tool description does not add any additional parameter semantics beyond what the schema already provides. It does not clarify when to use path vs. source or how target interacts, but the schema descriptions are sufficient for basic 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 description clearly states the tool's function: "Fast syntax/semantic check: compile and return only ok + diagnostics (no artifact)." It uses specific verbs and resources, and explicitly differentiates from sibling tools like ik_compile by noting it produces no artifact. This makes its purpose unambiguous.

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

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

The description provides clear usage context: "The quickest write-compile-fix feedback loop" implies use for rapid iterative development. However, it does not explicitly name alternatives or state when not to use this tool vs. siblings like ik_compile or ik_simulate. It gives a clear context but no 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 and discloses key behaviors: it returns success, diagnostics, and the hex/IR artifact, and it states that `import std/...` resolves automatically. It doesn't cover error specifics or side effects, but 'diagnostics' implies feedback and the overall behavior is clearly conveyed.

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

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

The description is three sentences, front-loaded with the primary action. Each sentence provides necessary context—what the tool does, what it returns, and when to use it—without filler or redundancy.

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

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

For a tool with no output schema and no annotations, the description adequately covers return values, emit modes, and the verification use case. Remaining gaps include the `report` parameter and explicit relationship to sibling tools, but overall it provides sufficient context for an agent to select and invoke 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?

Schema coverage is 60% and the description adds some value by clarifying that `source` and `path` are alternative inputs and that output format depends on `emit`. However, it does not explain the `report` parameter, which is undocumented in both schema and description, so it doesn't fully compensate for the coverage 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 states 'Compile ik source (inline `source` or a `path`) with the real ik8b compiler,' clearly identifying the verb, resource, and method. Mentioning that it produces Intel HEX or SSA IR artifacts distinguishes it from sibling tools like ik_check or ik_simulate, and the phrase 'real ik8b compiler' sets it apart from reference or tutorial tools.

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

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

The description explicitly instructs 'Use this to VERIFY any ik code you generate,' providing a clear when-to-use directive. It does not explicitly name alternatives or exclusions, but the verification context implies its role relative to other ik_* 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?

No annotations are provided, so the description carries the burden. It explains the tool's content and intended use, but does not explicitly state that it is a read-only reference or describe the response format. The reference nature is implied by its name and wording, but not fully disclosed.

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 information-dense sentence followed by a one-sentence usage directive. Every listed topic adds specificity, and the structure 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?

Given the tool's complexity and the absence of annotations/output schema, the description covers the key areas (lexing, IR, register allocation, ABI, etc.) and provides a clear invocation context. Including '--emit ir' adds practical depth, making it sufficiently complete for the agent to select the tool correctly.

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

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

The tool accepts zero parameters, so there are no parameter semantics to clarify. The schema shows an empty object, and schema coverage is effectively 100%; the baseline for no parameters is 4.

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

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

The description clearly identifies the tool as a deep reference for ik8b compiler internals and names specific subtopics (pipeline, SSA IR, register allocation, ABI, ISR codegen, fixed-point lowering, intrinsics, optimization). The verb 'reference' and the scope distinguish it from sibling reference tools like ik_grammar or ik_intrinsics.

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 sentence 'Use this to reason about the generated code' provides a clear use case. It does not explicitly exclude alternatives, but the compiler-internals focus implies when to prefer this over more general references.

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 communicates that the output includes memory layout and core family, which is useful, but it does not mention potential errors, exact return formatting, or whether this is a read-only operation. The description adds value but leaves several behavioral details unspecified.

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

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

The description is a single sentence that front-loads the core purpose and provides a clarifying parenthetical. Every word contributes to understanding the tool, 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 low complexity (one required string parameter), no output schema, and no annotations, the description covers the essential input semantics and expected return content. It is complete enough for basic usage, though it could be enhanced by explaining how to find available device names or what happens when an invalid name is provided.

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

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

Schema description coverage is 0%, and the description compensates partially by stating that the device is 'the value for target <device>', indicating that the 'name' parameter is a device identifier used in a target context. However, it does not explicitly name the parameter or provide format examples, so it adds only modest meaning beyond the schema's bare 'name' property.

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 identifies the tool as returning 'memory layout and core family' for 'one device', using a specific verb-like intent ('Memory layout and core family') and resource ('one device'). It distinguishes from sibling tools like ik_devices and ide_devices because it narrows to a single device rather than listing devices.

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 'for one device' and the parenthetical 'the value for target <device>' provide clear context that this tool is used when targeting a specific device. It does not explicitly mention alternatives like ik_devices for listing all devices, but the singular focus implies that distinction, so there is clear context without 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 full burden. It discloses the listing behavior and filter semantics, but does not mention the limit parameter (e.g., default of 100), pagination, ordering, or return format. For a read-only list operation, this is partial 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 two sentences, front-loaded with the core purpose and output fields, then filter details. Every word counts, with no redundancy or filler. Excellent structure.

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 and the lack of output schema, the description covers the essential purpose and filter behavior. It omits explanation of the limit parameter and return format, but these are minor gaps for a straightforward listing 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 has 0% coverage, so the description must compensate. It provides detailed semantics for the 'filter' parameter (substring or exact core family), but says nothing about the 'limit' parameter. This partial compensation keeps it at a borderline adequate score.

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

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

The description clearly states the verb 'List' and the resource 'supported AVR target devices', along with the specific fields returned. It does not explicitly differentiate from sibling tools like ik_device_info, but the scope is well-defined and unambiguous.

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

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

The description explains how to use the filter (substring match on device name or exact core family) and lists valid core families, implying when filtering could be useful. However, it provides no guidance on when to choose this tool over alternatives such as ik_device_info or ide_devices.

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

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

With no annotations, the description carries the burden. It states the dual behavior (list vs fetch source) but does not mention error handling, whether the operation is read-only, or any other side effects. For a simple listing tool this is adequate but not rich.

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?

One sentence, front-loaded with the key actions, and no superfluous words. The structure clearly presents the two modes separated by 'or'.

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 1 optional parameter and no output schema, the description conveys the essential behavior: list all or fetch source by name. It lacks some details like the return format of the source, but is sufficient given the low 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?

Schema coverage is 0%, so the description must compensate. It does by explaining that the 'name' parameter is the example's name and that omitting it triggers the list behavior, adding meaningful context beyond the bare schema.

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

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

The description uses specific verbs ('List', 'return') and names the exact resource ('bundled ik example programs', 'one example's source'), clearly distinguishing it from sibling tools like ik_tutorial or ide_examples.

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: list examples or fetch source by name. However, it does not explicitly contrast with alternatives such as ide_examples or ik_search, so the guidance is implicit rather than explicit.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It states the content ('complete formal EBNF grammar') but does not explicitly mention that the tool is read-only or returns a text string. However, given the nature of a grammar reference and zero parameters, the behavior is implicitly transparent, though not fully explicit.

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

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

The description is a single, front-loaded sentence that communicates the tool's essence without unnecessary words. It is appropriately sized for a simple reference tool and every word contributes to meaning.

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

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

Given the tool's simplicity (no parameters, no output schema, no annotations), the description is fully complete for its context. It clearly indicates what the tool provides—the complete grammar—and no additional details are necessary for an agent to effectively use it.

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

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

The tool has zero parameters and the input schema is empty, so the description has no need to explain parameter semantics. Per the rubric, 0 params warrants a baseline score of 4, and the description does not need to compensate for any undocumented fields.

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

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

The description clearly states that the tool provides the complete formal EBNF grammar of the ik language, which identifies the resource precisely. It distinguishes from sibling tools like ik_reference or ik_compiler_reference by specifying the grammar specifically, though it lacks an explicit verb like 'returns' or 'displays'.

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

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

The description provides no guidance on when to use this tool versus alternatives such as ik_reference or ik_tutorial. It neither mentions scenarios for use nor excludes any, leaving the agent to infer that it is for grammar lookups. This is minimal guidance, akin to no explicit usage 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?

With no annotations provided, the description carries the full burden of behavioral transparency. It discloses that the tool outputs signatures and notes for each intrinsic, and enumerates the exact set of intrinsics. This gives the agent a precise understanding of what the tool returns and its scope, which exceeds the minimal 'list' statement.

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 action ('List the compiler intrinsics') and then provides essential details (the specific intrinsics and the fact they include signatures and notes). Every word adds value, and there is no redundancy or filler.

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

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

Given the simplicity of the tool (no parameters, no output schema, no nested objects), the description is fully complete. It tells the agent exactly what the tool does, what it includes, and the scope relative to other tools. The inclusion of the actual intrinsic names further enriches the context, leaving no ambiguity about the tool's purpose.

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

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

The tool has zero parameters, and the schema confirms this with 100% coverage. The description does not need to explain parameters, and the baseline score for zero parameters is 4. It appropriately omits any parameter discussion since none exist.

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

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

The description clearly states the tool's purpose: to list compiler intrinsics with signatures and notes. It enumerates all the specific intrinsics (@nop @sei @cli @wdr @sleep @break @burn @swap @movw @mul @goto @spm @swtch), making it unmistakable what this tool covers. It distinguishes itself from sibling reference tools by explicitly noting these are the only built-in @-functions.

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: whenever a user needs information about compiler intrinsics. The statement 'These are the only built-in @-functions' effectively sets boundaries and differentiates it from other reference tools like ik_compiler_reference or ik_reference. It does not explicitly mention alternative tools, but the scope is 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 present, so the description carries the transparency burden. It states the tool is a 'cheat-sheet' covering specific topics, which clearly implies a read-only informational resource with no side effects. While it doesn't outline the output format, the description adequately conveys the tool's benign, educational nature.

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 core purpose ('Curated cheat-sheet'), lists topics in a coherent sequence, and ends with a clear directive. Every word earns its place; no fluff or redundancy.

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

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

For a simple informational tool with no parameters or output schema, the description is complete: it explains what the tool is, what content it covers, and when to use it. The low complexity means no further context is needed to enable effective selection and 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?

The tool has zero parameters and an empty input schema. Per the 0-parameter baseline of 4, the description doesn't need to add parameter details. The description instead adds value by explaining the tool's content, which is appropriate for a parameterless tool.

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

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

The description clearly identifies the tool as a curated cheat-sheet for the ik language and lists specific topics (sigils, assignment, program shape, types, memory spaces, control flow, interrupts, minimal program). This distinguishes it from sibling tools like ik_tutorial or ik_reference by framing it as an overview to read first.

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

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

The instruction 'READ THIS FIRST before writing any ik code' provides explicit when-to-use guidance as an initial orientation. It does not mention alternatives or when-not-to-use, but the 'first' directive strongly implies prioritizing this tool over others in the documentation set.

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 disclosure. It reveals significant behavioral traits: it is parser-based (not fuzzy), returns a specific set of structural data, and optionally runs the real compiler for authoritative errors. It also discloses the inheritance semantics of `target` across files. It does not explicitly state it is read-only, but the term 'analyze' strongly implies non-mutating behavior, which 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?

The description is a single dense paragraph that front-loads the key purpose and enumerates concrete return items. Every sentence adds useful information, but it is long and somewhat run-on; a list or clearer sentence breaks would improve scannability. Still, it avoids redundancy and earns its length.

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

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

Given the tool's complexity (multi-file project analysis) and the absence of an output schema, the description compensates well by explicitly enumerating the return values (import graph, target and declaration location, @main entry, per-file exports, cross-file problems) and the optional diagnostics mode. It also provides procedural context for when to use it. This is a complete and self-contained description.

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

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

The input schema already provides 100% description coverage for all three parameters, so the baseline is 3. The description adds value by clarifying that `path` can be a directory or a single file, and that `files` can be used 'instead of a path', plus explaining the effect of `include_diagnostics` as 'compile the entry point for authoritative errors'. This goes beyond the schema's default 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 function with a specific verb ('Understand') and resource ('multi-file ik project structurally'), and differentiates itself from alternatives by emphasizing 'exact, parser-based — not fuzzy search'. It enumerates specific outputs (import graph, target, @main, exports, problems), making the purpose distinct from sibling tools like ik_compile or ik_check.

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 when-to-use guidance: 'Use this BEFORE editing an existing project so you write in the right context' and gives a concrete example of why ('don't re-declare target in imported files'). While it does not name specific alternative tools, it implies a contrast with fuzzy search and clearly scopes the intended use case, but lacks explicit when-not-to-use or named alternatives.

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

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

With no annotations, the description carries the full burden. It discloses that the output is plain text and the action is read-only via the verb 'Read', but it omits details like error handling, return format specifics, or any security considerations. This is adequate but has clear 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, front-loaded sentence followed by a compact list of topics. Every element is necessary and there is no redundant information, making it highly 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 simple one-parameter tool, the description provides the core action and valid inputs, but lacks guidance on when to prefer this over sibling tools and does not describe the output's format beyond 'plain text'. It is moderately complete but leaves room for clearer differentiation and behavioral expectations.

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 lists the allowed topics, essentially mirroring the schema's enum values. It doesn't add meaning beyond the schema, such as explaining case sensitivity or how the topic maps to chapters, but it does make the parameter's purpose obvious.

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 reads a language-reference chapter as plain text, with a specific verb ('Read') and resource. It lists the available topics, which helps distinguish it from general reference tools, though it doesn't explicitly differentiate from sibling tools like ik_grammar or ik_intrinsics that cover specific topics.

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 topic list implies when to use this tool (e.g., when you need a chapter on 'lexical' or 'types'), providing clear context. However, it offers no explicit alternatives or exclusions, such as pointing to ik_compiler_reference for compiler details or ik_grammar for grammar-specific queries.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It states exactly what the tool searches and the return fields (scope/file/line). It does not cover query syntax or result limiting, but the disclosed behavior is clear and non-misleading.

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

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

The description is a single, front-loaded sentence with no filler. Every word earns its place, covering scope, action, and return format 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?

The tool has no output schema and no annotations, so the description must explain return values and behavior. It states the return format and searched sources, but omits how 'max_results' behaves, query syntax, and any edge cases. This makes it minimally viable but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. The 'query' parameter is inferable, but 'max_results' is entirely undocumented in both the schema and the description. The description adds no concrete parameter semantics beyond the search 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 uses a specific verb+resource structure: 'Full-text search across the language reference, stdlib docs, tutorial, toolchain docs, std/ sources, and examples.' It clearly distinguishes from sibling tools that target individual references or modules by covering all documentation sources, and it reports the return format (matching lines with scope/file/line).

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

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

The description implies usage: when you need to search across all docs rather than consult a specific reference. However, it does not explicitly state when not to use it or name alternatives, leaving the agent to infer the decision from context.

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

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

With no annotations provided, the description carries the full burden. It discloses that source is compiled before running, that the target is selected from the source, and that output includes register dumps, peek bytes, and an optional trace. It also notes interrupt injection capability. This is solid but not exhaustive; it doesn't mention error behavior, side effects, or the absence of real hardware effects.

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

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

The description is three sentences, front-loaded with the core purpose. Every sentence adds value: input modes, output contents, and interrupt capability. No fluff or repetition; excellent structure.

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 13 parameters, no output schema, and no annotations, a three-sentence description is insufficient. It outlines the main flow but omits details on interrupt injection parameters, limits, dump behavior, and peek length. Agents may struggle to construct complex simulation requests with this level of guidance.

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

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

Schema description coverage is only 23% (only path, source, and target have descriptions). The tool description adds meaning for source/path, hex_path+mcu, peek, trace, and interrupts, but leaves many parameters unexplained (irq, irq_at, irq_every, limit, dump, peek_len). It cannot compensate for the low schema coverage and does not give the agent enough to confidently use 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 opens with a specific verb+resource: 'Run code on the ik8bvm AVR core simulator.' It goes on to list input modes and outputs, clearly distinguishing it from sibling tools like ik_compile or ik_check. This is a textbook example of a clear, unambiguous 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 gives clear context: you can either provide ik source/path or a hex_path+mcu, and it describes what the simulator returns. This makes the use case obvious. However, it doesn't explicitly state when to prefer this over alternatives or 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?

No annotations are provided, so the description must disclose behavior. It describes a read-only diagnostic operation (resolving paths, checking availability) and does not mention any side effects. However, it doesn't explicitly state that it's non-mutating or require any prerequisites, leaving some ambiguity about potential failures or environment requirements.

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

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

The description is a single sentence that front-loads the purpose with 'Diagnostics:' and lists the specific outputs. Every word earns its place, with no redundancy or filler.

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

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

Given the tool's low complexity (0 params, no schema requirements), the description covers the main purpose and output areas. It doesn't state the return format, and since there's no output schema, an agent may not know the exact structure, but the core functionality is clear enough for a simple diagnostic 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 there is nothing to explain beyond the schema. The description correctly omits parameter details, and the baseline for 0 params is 4.

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

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

The description begins with 'Diagnostics:' and specifies exactly what is reported: resolved toolchain root, compiler/simulator binary paths, and documentation source availability. This clearly distinguishes it from siblings like ik_compile or ide_status, which focus on compilation or IDE state respectively.

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 word 'Diagnostics' implies it's for checking the environment, and the listed items (toolchain root, binary paths) suggest when to use it, but there is no explicit guidance on when to choose this over alternatives like ide_status or when not to use it. The 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 carries the full burden. It discloses the output content (one-line summary, target dependency, function count) and implies a read-only listing operation. It does not explicitly state side effects, but for a list tool this is reasonably implicit.

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, information-dense sentence front-loads the main action ('List every standard-library module') and packs what is included. 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, no-output-schema tool, the description fully covers what the tool returns and the scope. It is sufficiently complete for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds context about the 'selected target' which informs the dependency field, enhancing understanding beyond the empty schema.

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

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

The description clearly states the tool's function: listing every standard-library module with specific details (summary, target dependency, function count). The verb 'List' and resource 'standard-library module' are specific, and it distinguishes from sibling ik_stdlib_module by explicitly covering all modules rather than a single one.

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

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

The description clearly conveys when to use this tool: when you need an overview of all standard-library modules. It does not explicitly mention alternatives or exclusions, but the context is unambiguous given the sibling tool names.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clarifies that the tool returns function signatures, summaries, reference docs, and optionally source, which is useful. However, it does not state whether the operation is read-only, potential errors, or performance characteristics. For a documentation retrieval tool, this is acceptable but not rich.

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 no wasted words. It efficiently conveys the scope, contents, and input format.

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

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

The description explains what the tool returns (signatures, summary, reference doc, optional source) and the expected input format. It lacks details on error handling or edge cases (e.g., invalid module names), but for a straightforward documentation tool, the description is sufficiently complete given 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 0%, but the description adds meaning by explaining that 'name' takes a module identifier like 'gpio' or 'std/gpio', and 'include_source' corresponds to optional source inclusion. This provides context that the bare schema lacks, though it could be more explicit about the include_source parameter's effect.

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 this tool returns the full API for one stdlib module, including public function signatures, summaries, reference docs, and optionally source. It distinguishes from siblings like ik_stdlib_list (which likely lists modules) and ik_search by focusing on a single module's complete API.

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

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

The description implies usage: when you need a specific module's full API documentation. It provides input format examples ('gpio' or 'std/gpio') but does not explicitly mention when not to use it or compare with alternatives such as ik_stdlib_list or ik_search. The guidance is adequate but not explicit.

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

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

With no annotations, the description carries the burden of disclosing behavior. It clearly explains the no-argument behavior (list pages) versus argument behavior (read a page). It does not mention edge cases like invalid page names or the exact return type, but for a simple documentation reader this is reasonably transparent.

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

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

The description is exceptionally concise: two sentences, front-loaded with the primary action ('Read a tutorial page'), followed by the list-mode behavior and supported pages. Every word adds value, and there is no fluff 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 (one optional parameter, no output schema, no annotations), the description covers the core behaviors and valid inputs. It could be more complete by specifying what happens on invalid page names or what the output looks like, but for a tutorial reader these gaps are minor. Overall, it provides enough context for correct usage.

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

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

Schema coverage is 0% with no parameter descriptions. The description fully compensates by explaining that the 'page' parameter is optional and listing all acceptable values. It also clarifies that omitting the parameter triggers listing mode, giving the agent complete semantic understanding beyond the bare schema.

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

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

The description clearly states the tool's function: 'Read a tutorial page, or list pages when no argument is given.' It uses a specific verb (read/list) and identifies the resource (tutorial pages). By listing the exact pages (index, installing, firstprogram, tour, stdlib, interrupts), it distinguishes itself from sibling reference/compiler 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 clear usage context: pass a page name to read it, or omit the argument to list pages. It also enumerates valid page values, guiding correct invocation. However, it does not explicitly contrast with sibling tools (e.g., when to use ik_reference instead), though the 'tutorial' framing implies the intended scope.

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

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

No annotations are provided, so the description carries the full burden. It clearly conveys that this is a non-mutating reference by using the word 'reference' and by listing content rather than actions. It also mentions 'explicit limitations', adding transparency about what the tool covers and does not. It does not explicitly state side-effect-free, but the nature strongly implies it.

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 purpose ('Deep reference for the ik8bvm AVR simulator') and backed by a dense list of covered areas. Every word adds value, and there is no repetition or filler.

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

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

For a reference tool with no parameters and no output schema, the description is exceptionally complete. It names the simulator, enumerates the specific content covered, and states the intended use case. It also notes the inclusion of limitations, giving the agent a full picture of what to expect.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter semantics, and the empty schema already communicates that no arguments are required. The description appropriately focuses on what the reference contains rather than parameter details.

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

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

The description clearly identifies the tool as a deep reference for the ik8bvm AVR simulator, listing specific topics (core classes, register file, SREG flags, memory map, instruction set, peripherals, cycle counting, limitations). This distinguishes it from sibling reference tools like ik_compiler_reference and ik_reference by focusing on VM internals and simulation behavior.

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

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

The description explicitly states when to use the tool: 'Use this to reason about simulation behaviour.' It provides a clear context but does not explicitly mention exclusions or alternatives. Given the many sibling reference tools, a note about not using it for compiler or grammar questions would elevate it, but the guidance is sufficient.

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