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 forward-only behavior (irreversibility), handling of user-modified files (skipped and reported as conflicts), and the current no-op behavior ('Today no patches ship'). This is good behavioral transparency, though it could mention permissions or explicit side effects.

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

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

The description is concise (three sentences), front-loaded with the core purpose, and every sentence adds useful information (forward-only, conflict handling, current empty state, future path). No redundancy.

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

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

The description sufficiently covers the tool's behavior, current status, and future evolution. It mentions the output ('empty applied list') and the patch location ('templates/patches/<version>/'), which is complete for a parameterless tool with an output schema.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. The description adds no parameter details, but none are needed. Baseline for 0 params is 4, and no reason to lower.

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: 'Apply every pending shipped patch to the project harness.' This is a specific verb ('apply') and target resource ('project harness'), and it distinguishes the tool from siblings like keystone_harness_bootstrap by focusing on patch application.

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

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

The description provides clear context: it is used to apply shipped patches, with the caveat that patches are forward-only and user-modified files are skipped and reported as conflicts. It implies the tool is used for incremental updates but does not explicitly name alternatives or state when not to use it.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It mentions the composition of the envelope (rules, reasoning, skills, commands) but does not state whether this is a read-only operation, whether it has side effects, or what the output structure looks like beyond those high-level components.

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 easy to scan and front-loads the key outcome. However, its brevity sacrifices important context that would improve usability, so it is not a perfect score.

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

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

Despite the presence of an output schema, the description provides very little context for usage. It does not explain how to discover valid topics, what actions to take with the envelope, or how this fits into the broader workflow with the many sibling tools. The tool appears moderately complex given the rich output, but the description leaves significant 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 a single required 'topic' string with 0% description coverage. The description adds only 'for a topic', which is minimal and somewhat redundant. It does not clarify topic naming, valid values, relationship to keystone_list_topics, or provide examples, leaving the parameter underdocumented.

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

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

The description clearly states the tool returns a 'full envelope' containing rules, reasoning, skills, and commands for a given topic. Though it lacks an explicit verb, the tool name and phrasing make the retrieval intent clear, and it distinguishes itself from sibling creation 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?

No guidance is provided on when to use this tool versus alternatives like keystone_list_topics or the new_* creation tools. There is no mention of prerequisites, such as whether the topic must already exist or if this should be called after creating resources.

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

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

The description discloses idempotency ('Idempotent'), no-overwrite behavior ('never overwritten'), and that existing items are reported in `skipped`. With no annotations to fall back on, this fully covers the behavioral contract.

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

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

Three compact, front-loaded sentences deliver purpose, behavior, and parameter guidance without waste. Every clause adds distinct information (created artifact, idempotency, usage, parameter implications).

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

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

For a single-parameter bootstrap tool, the description covers what, when, why, and parameter effects. The presence of an output schema handles return details, so the description completes the picture.

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 sole parameter `materialize_templates` is explained precisely: passing False yields 'bare-bones directory layout only (no shipped state ledgers, sensors, actions, or playbooks)'. This compensates for the schema's 0% parameter 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 opens with a clear verb-resource pairing: 'Create `.keystone/harness/` and (by default) materialize the shipped template tree.' It distinguishes itself from sibling scaffolding tools by noting it is a prerequisite ('Call this once per project before scaffolding individual guides / sensors / actions / playbooks').

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

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

Explicit when-to-use guidance is provided: 'Call this once per project before scaffolding...' It also explains when to opt out of the default behavior ('opt out only for advanced use cases'), giving clear decision criteria.

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

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

There are no annotations, so the description carries the full burden. It clearly states the action (list) and the scope (configured topics), implying a read-only operation, and mentions the filtering behavior. However, it does not disclose behaviors like tag matching semantics, ordering, pagination, or potential errors.

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

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

The description is two short sentences, front-loaded with the core purpose and no superfluous words. Every part earns its place.

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

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

Given the tool's simplicity (one optional parameter, an output schema present), the description covers the essential use case. It lacks richer context around filter semantics and when to select this tool, but that is a minor gap for a straightforward list operation.

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

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

The schema has 0% description coverage, so the description must compensate for the sole parameter. It does add meaning by stating the tag is used to filter, which is not in the schema. Yet it leaves details ambiguous, such as whether the filter is an exact match or substring, limiting full semantic clarity.

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 ('List') and a concrete resource ('configured topics'), and immediately distinguishes itself from the sibling creation tools (e.g., keystone_new_*). The mention of the optional tag filter further refines the purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The only usage hint is 'Pass `tag` to filter', which is a parameter instruction, not a when-to-use guideline.

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 behavioral burden. It discloses the creation of a markdown file at a path, but it does not mention side effects such as whether existing files are overwritten, how the `force` flag affects behavior, or any prerequisites/permissions. This is a significant gap for a scaffolding tool that mutates the filesystem.

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

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

The description is front-loaded with the concrete action and path in the first sentence, then adds concise conceptual context with examples and sibling distinctions. No sentences are wasted.

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 (2 params, no nested objects) and an output schema exists, so return values don't need explanation. But the description omits the meaning/effect of `force` and any overwrite behavior, leaving an agent to guess. It adequately explains purpose and relation to playbooks/skills, but not enough for full autonomous invocation.

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

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

The `name` parameter is indirectly explained by the `<name>.md` placeholder in the path. However, the `force` parameter is not described at all, and schema coverage is 0%, so the description must compensate but fails to do so for half the 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 ('Scaffold') and resource ('new action markdown') plus the exact destination path (.keystone/harness/actions/<name>.md). It also distinguishes actions from playbooks and skills, though it does not contrast with every sibling new_* tool.

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

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

It provides clear usage context by defining actions as 'short, focused operations' and explicitly contrasts them with playbooks (orchestration) and skills (procedural how-to via skill://). This gives the agent enough to choose between this tool and the most closely related siblings.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It states the main effect (creating a directory) but does not mention what files are scaffolded, the effect of the 'force' parameter, or any destructive aspects. Minimal behavioral disclosure for a scaffolding/mutation tool.

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

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

The description is a single, clear sentence with no filler. It front-loads the action and location, making it easy to parse. 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 description is too thin for a scaffolding tool. It lacks context about what an adapter is, when to use this tool, how the force parameter behaves, and what the scaffolded output looks like. The output schema covers return values, so that is not a gap, but the missing behavioral and usage context is significant.

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

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

Schema description coverage is 0%, so the description must compensate. It provides some meaning for the 'agent' parameter by embedding it in the target path, but the 'force' parameter is entirely unexplained. The description adds partial value but does not fully clarify both 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 uses a specific verb ('scaffold') and names a distinct resource ('per-agent adapter directory') with a concrete location, distinguishing it from sibling tools like keystone_new_guide or keystone_new_sensor. It clearly states what the tool creates.

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

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

No guidance is given on when to use this tool versus alternatives. It does not mention prerequisites, when to choose this over other keystone_new_* tools, or any exclusions. The existence of sibling tools makes this lack of differentiation a clear gap.

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

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

With no annotations, the description must disclose behavioral traits, and it does reveal the file creation path and content scope. However, it doesn't mention what `force` does, whether existing files are overwritten, whether directories are created, or what other side effects occur during scaffolding.

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

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

The description is compact and front-loaded: the first sentence states the action and target path, and the second clarifies what belongs in a corpus. Each sentence earns its place 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?

The description covers purpose, placement, and content categorization, and the output schema can convey return values. But it omits `force` semantics, prerequisites (e.g., an existing harness), and failure behavior, leaving notable gaps for a creation tool with no annotation support.

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

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

Schema description coverage is 0%, so the description must compensate. It only gives meaning to `name` via the path `<name>.md`; the `force` parameter is not mentioned at all. This is insufficient for a two-parameter tool.

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

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

The description opens with a specific verb and resource: 'Scaffold a new corpus markdown under `.keystone/harness/corpus/<name>.md`.' It clearly distinguishes this from sibling tools by defining corpus entries as reasoning/background context and contrasting them with guides, actions, playbooks, and skills.

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: for domain notes, architecture decisions, and idioms. It also tells when not to use it by directing constraints to `guides/` and procedures to `actions/`, `playbooks/`, and `skills/`, naming the 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, and it does disclose the tier strictness cascade, which is important behavioral context. However, it does not disclose behaviors like overwriting existing files (related to `force`) or error conditions, so transparency is only partial.

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

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

The description is concise and efficient, with two sentences that deliver the essential information. It front-loads the purpose and then explains the tier system without excess.

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

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

The description provides the core purpose and the important tier semantics, but it omits details about the `force` parameter and any behavioral notes about file creation. Given the simplicity of the tool, it is mostly complete, but the missing parameter explanation leaves a gap.

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

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

The description adds meaning for the `tier` parameter, explaining the three allowed values and their hierarchy, which the schema does not do. However, `name` and `force` receive no explanation, leaving them to be inferred from their names alone.

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

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

The description clearly states the tool's function: scaffolding a new guide markdown file in a specific directory. The verb 'Scaffold' and the resource 'guide markdown file' make it distinct from sibling tools like keystone_new_script or keystone_new_sensor.

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

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

It provides clear context that this tool is for creating guides, which differentiates it from other new tools. However, it does not explicitly state when not to use it or mention alternatives, leaving room for ambiguity in tool selection among siblings.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It states that it scaffolds a markdown file, but it does not mention important side effects such as whether it overwrites an existing file, what the `force` parameter does, or any filesystem impacts beyond the path. Since 'force' is a parameter, the behavior likely involves handling existing files, but the description leaves this ambiguous.

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

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

The description is brief and front-loaded with the primary action. The additional explanation of playbooks and phase gates is useful context and does not feel wasted. It stays within a few sentences and is well-structured, though the phase gate list is somewhat tangential to the scaffold operation itself.

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

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

Given that this is a scaffolding tool with an output schema and two parameters, the description is incomplete. It does not explain the `force` parameter, the behavior when the file already exists, or what the generated playbook contains. The context about phase gates helps but does not cover essential operational details. The output schema exists, so return values need not be described, but the tool's side effects and parameter semantics remain unclear.

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 provides only parameter names and types, with no descriptions, and the tool description also does not explain the parameters. `name` is evident from the path template, but `force` is completely unexplained. The description adds no meaning beyond the schema, and with 0% schema description coverage, this is a major 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 begins with a specific verb 'Scaffold' and clearly states the resource ('a new playbook markdown') and its destination (under `.keystone/harness/playbooks/<name>.md`). It also differentiates from sibling tools like keystone_new_guide or keystone_new_sensor by defining what a playbook is, making it unambiguous what this tool creates.

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

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

The description explains the purpose of playbooks ('orchestrate multiple actions into a higher-level flow') which implies when to use this tool—when you need a multi-action orchestration file. However, it does not explicitly state when not to use it or compare against alternative tools like keystone_new_script or keystone_new_action. There is no direct 'use this instead of X' guidance, but the context is sufficient to infer the general use case.

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 states the scaffold effect (creating a markdown file) but does not mention side effects like overwriting behavior, what 'force' does, or whether the operation is safe or destructive. The description is too sparse on behavioral details.

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

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

The description is concise and front-loaded with the main purpose. Every sentence adds context, and it avoids unnecessary repetition of the tool name.

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

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

The description covers the core purpose and relation to inferential sensors, and an output schema exists to explain return values. However, it omits key behaviors (body/force semantics) and does not fully contextualize when to use this tool versus other new_* siblings beyond new_sensor.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at the 'name' parameter via the file path template. The 'body' and 'force' parameters are completely unexplained, leaving significant gaps in understanding the input 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 a specific verb 'Scaffold' with a clear resource: a prompt markdown file under a defined path. It distinguishes itself from sibling tools by explaining the inferential sensor connection and explicitly mentions keystone_new_sensor as the alternative that stamps the prompt automatically.

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

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

The description gives clear usage context: this tool is for inferential sensors. It also provides an explicit alternative: most projects should use keystone_new_sensor(mode='inferential') instead, which implies when to prefer the sibling over this tool.

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

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

With no annotations provided, the description carries the full burden. It discloses that new scripts are chmod +x, and that force=True refreshes an existing script. However, it doesn't explicitly describe error behavior when the script exists without force, or confirm what happens with a null body. Still, the key behavioral traits are surfaced.

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

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

The description is compact, front-loaded with the core purpose, and every sentence provides useful information. It uses four sentences to convey purpose, usage, alternatives, and key behaviors without any 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 moderate complexity (3 params, no annotations), the description covers the main use case, refresh flow, permission behavior, and explicit alternative. The output schema handles return values, so the description is sufficiently complete for an AI agent to select and 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?

The input schema has no parameter descriptions (0% coverage), so the description must compensate. It does so by explaining that 'body' is the script body, 'name' appears in the file path, and 'force' is needed to refresh. However, it doesn't detail the default null body behavior or the exact outcome when force is false and the file exists, leaving some ambiguity.

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

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

The description clearly states the tool scaffolds a shell script under a specific path, with a specific verb 'scaffold' and a resource. It also distinguishes itself from keystone_new_sensor, which is the alternative for sensor scaffolding.

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

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

The description explicitly says when to use this tool ('drop a script body without a sensor wrapper, or to refresh an existing script') and when to prefer an alternative ('Most projects scaffold sensors via keystone_new_sensor'). It also mentions the force=True refresh path, giving usage context.

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

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

With no annotations, the description carries the transparency burden. It discloses what files are stamped (`scripts/<name>.sh` or `prompts/<name>.md`), exit code semantics (0 = pass, non-zero = fail), and PASS/FAIL reporting for inferential mode. This gives the agent a solid behavioral model, though it omits details about `force` behavior.

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

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

The description is appropriately sized, front-loaded with the core purpose, and uses bullet lists for modes and kind values. Every sentence adds value and the structure makes the information quickly scannable for an agent.

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 existence of an output schema (which likely documents return values) and the moderate complexity of a scaffolding tool, the description covers the essential behavioral aspects: what gets created, how it runs, and how it reports. It could be more complete by explaining `force` semantics or prerequisites, but overall it's sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains `mode` (computational vs inferential with full semantics) and enumerates valid `kind` values, adding meaning beyond the schema. However, `force` is not described at all, and `name` is left implicit, leaving a coverage gap for two of four 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 clear, specific verb+resource: 'Scaffold a new sensor + its matching implementation.' It further differentiates from siblings by detailing the sensor-specific artifact types (scripts vs prompts) and execution model, making the tool's purpose unmistakable.

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

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

The description provides clear context on when to use each mode (computational for shell scripts, inferential for reasoning prompts) and explains kind as an informational category. It does not explicitly exclude alternatives or reference sibling tools, but the mode selection guidance is actionable and sufficient for an agent.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the naming convention (prepending 'keystone-') and explains the skill discovery mechanism. However, it omits critical behaviors such as what happens when the target directory exists, the effect of the 'force' parameter, or whether any files are overwritten. This leaves meaningful gaps for a scaffolding tool.

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

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

The description is composed of three short paragraphs, each adding relevant information: the action, the context/ecosystem, and the naming behavior. It is efficient and front-loaded with the core purpose, though the second paragraph could be seen as slightly verbose for a tool description. Overall, well-structured and without redundancy.

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

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

The description gives a strong conceptual foundation (what a skill is, how it is surfaced) and the naming rule, but it falls short on parameter semantics and doesn't explain the behavior of the 'force' flag or the expected output. Since an output schema exists, return values are less critical, but the missing parameter details leave the description incomplete for a 3-parameter tool with no schema descriptions.

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

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

Schema description coverage is 0%, so the description must compensate. It provides useful context for the 'name' parameter by showing it in the target path and explaining the prefix rule. But it says nothing about the 'force' or 'description' parameters, leaving the agent to guess their roles. This is insufficient given the lack of schema-level descriptions.

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

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

The description opens with a specific verb ('Scaffold') and a concrete resource ('.keystone/harness/skills/<name>/SKILL.md'), making the tool's function unmistakable. It clearly distinguishes itself from the many sibling 'new_*' tools by naming the skill-specific directory and file structure, ensuring an agent knows this is the skill scaffolder.

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

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

The description explains that skills are for 'agent-discoverable procedural how-to' and that the scaffolder handles naming conventions, which implies when to use this tool. It lacks explicit exclusions or direct comparisons to alternatives like keystone_new_guide or keystone_new_prompt, but the context is clear enough for an agent to infer the primary use case.

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

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

No annotations are provided, so the description carries the full burden. It explicitly discloses overlay semantics: only the region between `<!-- BEGIN KEYSTONE -->` and `<!-- END KEYSTONE -->` is rewritten, preserving pre-existing user content. This is a significant behavioral detail that goes beyond a simple 'install' 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 appropriately sized with four sentences, each adding value: purpose, what menu files are, overlay semantics. It is front-loaded with the main action and does not waste 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?

The description covers the core behavior and critical overlay semantics, and an output schema exists so return values need not be described. However, it does not explain what the 'force' parameter does or any prerequisites (e.g., whether the harness must already exist), which is a minor gap given the tool's complexity.

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

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

The description adds meaning for 'agent' (whose menu files) and 'project_root' (install location), but 'force' is not explained at all. With 0% schema description coverage, the description partially compensates but leaves a gap for the force parameter's behavior.

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

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

The description opens with a specific verb+resource+location: 'Install the agent's menu file(s) at the project root.' This clearly states what the tool does and mentions menu files (CLAUDE.md, AGENTS.md) which distinguishes it from siblings like keystone_harness_bootstrap. It is not vague or tautological.

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: menu files are thin pointers to the harness and MCP server, so the tool is used to install these lightweight pointers. However, it does not explicitly compare with alternatives or state when not to use it, making it a 4 rather than a 5.

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