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

With no annotations provided, the description carries full burden for behavioral disclosure. It adds valuable context: atomicity, project-files isolation under '.worktrees/<claim-id>', sparse-checkout omission of backlog, and preservation of 'outcomes, rejection fields, and exit codes.' However, it leaves many behavioral questions unanswered, such as conflict/locking behavior, side effects on existing claims, and actual exit-code semantics. The level of detail is moderate, not comprehensive.

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 a clear one-line purpose, followed by scope-specific details and a compatibility note. It is relatively compact, but the final sentence about 'Schema-version-2 results' is cryptic and adds more confusion than value. Overall structure is logical but could be clearer.

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 highly complex (23 parameters, 5 required, no annotations), and the description does not cover essential invocation details like the meaning of required fields (repository, claim_id, agent, task, root_task_id), error outcomes, or how this relates to other claim operations. The presence of an output schema offsets the need to describe return values, but the input semantics are only partially explained. This is insufficient for confident invocation without further investigation.

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 17%, so the description must compensate for 23 parameters. It does clarify some parameter relationships, such as work_item_id with activity, and named resources requiring timing evidence against PROJECT.yaml. Yet most parameters (base, files, trees, branch, parent_claim_id, expected_duration_seconds, etc.) receive no explanation in either the schema or description. The description provides scope-level semantics but does not adequately cover the parameter space.

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 types: 'Atomically acquire one work item, file domain, or timed resource.' This clearly distinguishes claim_acquire from sibling lifecycle tools like claim_report, claim_status, and claim_release. The scope details further refine what 'acquire' means in different modes.

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

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

The description provides context for when to use this tool by outlining three acquisition scopes (work-item, file domain, timed resource) and their prerequisites, such as 'complete timing evidence resolved against PROJECT.yaml.' However, it does not explicitly compare this tool to alternatives like claim_extend or claim_release, nor state when NOT to use it. The usage guidance is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses atomicity, non-weakening behavior, a specific error code (SHARED_CHECKOUT_REQUIRED), and the rollback guarantee for invalid mixed scope. This goes well beyond a generic 'extends scope', though it omits many operational details (permissions, rate limits, 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?

Three sentences, with the main action front-loaded in the first sentence. Each sentence adds a distinct behavioral constraint. The dense domain jargon slightly reduces readability, but overall it is appropriately sized.

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

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

The tool has 14 parameters and no annotations, but the description covers only a narrow set of edge cases and no invocation prerequisites. It doesn't explain how required parameters (repository, claim_id) relate to the extension, nor what constitutes 'same-domain'. Despite an output schema, a user would struggle to form a correct request.

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 29%, yet the description provides no parameter-level guidance. Terms like 'operational scope', 'named resource extension', and 'Primary-only scope' remain undefined and are not mapped to any of the 14 parameters. The description therefore fails to compensate for the low 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 opens with a clear verb and resource: 'Atomically add same-domain scope' – specific to extending a claim's scope without weakening ownership. This distinguishes it from siblings like claim_acquire (new claim) and claim_extend_deadline (deadline extension). Though terse, the purpose is unambiguous.

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

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

The description implies usage for extending an existing claim's scope, but never explicitly says when to use this tool versus claim_acquire/claim_extend_deadline. It offers constraints and error conditions rather than decision guidance. This is implied usage at best, with no exclusions or alternatives named.

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, but it only states the action and a vague evidence bound. It does not mention whether this mutates state, what 'bounded' means, what permissions are needed, or any failure modes.

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

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

The description is a single sentence that is front-loaded with the verb and target, with no filler. It is concise, though the terseness contributes to missing critical guidance.

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

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

For a tool with four required parameters, no annotations, and a sibling tool named claim_extend, this description leaves major gaps in usage differentiation and behavioral context. The existing output schema does not compensate for the missing parameter and usage information.

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, but it does not explicitly map any of the four parameters. It offers vague conceptual hints ('bounded evidence', 'hard stop') but fails to clarify claim_id, repository, requested_hard_stop_duration_seconds, or extension_evidence.

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 ('Extend') and identifies the resource ('configured resource hard stop') and a constraint ('bounded evidence'), making the core action clear. However, it does not distinguish this tool from the sibling tool claim_extend, so it stops short of a perfect score.

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

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

There is no guidance on when to use this tool versus alternatives like claim_extend. The phrase 'bounded evidence' hints at a requirement, but no explicit usage context, prerequisites, or exclusions are provided.

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

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

With no annotations, the description carries the full burden of transparency. It does not disclose side effects (e.g., updating a timestamp), failure behaviors (e.g., what if claim is not active), or any permissions needed. The term 'heartbeat' is domain-specific and not explained, leaving behavioral traits 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 a single, well-structured sentence that delivers the core purpose without wasted words. It is front-loaded with the action and resource, making it easy to absorb.

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 having an output schema and only two parameters, the description leaves key domain context unexplained. An agent wouldn't know what 'heartbeat' means, when to refresh it versus other claim operations, or what the response represents. The description is minimal and does not provide enough information for correct invocation in a broader workflow.

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

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

The schema has 0% description coverage, so the description must compensate. It neither explains that claim_id identifies the specific claim nor that repository scopes the registry. While the parameter names are somewhat self-explanatory, the description adds no extra meaning about formats, constraints, or relationships beyond the schema field names.

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

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

The description clearly states a specific action ('Refresh') and a specific resource ('one active claim heartbeat'), and notes the scope ('repository-global registry'). It distinguishes from sibling tools by emphasizing 'heartbeat' as opposed to acquire, extend, release, etc. However, it does not explicitly differentiate from similar tools like claim_status or claim_extend_deadline.

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. The description only says what it does, not when it should be chosen over claim_extend, claim_release, or claim_maintain_journal. There are no usage scenarios, prerequisites, or exclusions.

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

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

With no annotations, the description carries the full burden. It states the core action (archive) and the retention of a hot window, but does not disclose side effects such as whether archiving deletes data, whether it is reversible, what permissions are required, or the impact on the journal. This is insufficient for a maintenance operation.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to conveying the core action and constraint, making it concise and easy to parse.

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?

While an output schema exists, the description still lacks important context such as when to use the tool, prerequisites, and operational behavior. For a maintenance operation that may have side effects, this level of detail is insufficient. The description is too sparse to fully inform an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It implicitly explains 'hot_days' via 'hot window', but 'repository' is never mentioned. The description adds some meaning to one parameter but leaves the other undocumented, which is inadequate for a 2-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 uses a specific verb 'Archive' with a clear resource ('complete UTC claim-event days') and states the retention behavior ('retaining the configured hot window'). This clearly distinguishes the tool from siblings like claim_report, claim_status, claim_acquire, etc., which perform different actions.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. No exclusions, prerequisites, or context are mentioned. While the purpose is clear, there is no explicit 'use this when' or 'instead of' information.

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 only vague mentions a 'disposition for work-item ownership' but does not disclose side effects, reversibility, ownership requirements, or potential failures. For a release operation, this is a significant gap.

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

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

The description is a single sentence with no fluff, front-loaded with the action verb. It is concise and structured adequately, though it could be more informative. It earns its place but sacrifices substance for brevity.

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

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

Given no annotations, an output schema (not shown), and four parameters, the description is far too sparse. It omits usage context, behavior, and parameter details, leaving the agent with insufficient information to invoke the tool reliably. The presence of an output schema does not compensate for these gaps.

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

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

With schema description coverage at 0%, the description must compensate by explaining the parameters, but it only hints at 'disposition' and does not clarify the meaning or expected format of claim_id, repository, or blocker_reference. The mention of 'exact claim' implies precise identification but adds no concrete semantic value.

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

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

The description states a clear action ('Release one exact claim') on a specific resource (a claim), and the phrase 'including a disposition for work-item ownership' adds useful specificity. It is not a tautology and is distinguishable from sibling tools like claim_acquire or claim_extend, though it does not explicitly name alternatives.

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

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

The description offers no guidance on when to use this tool versus alternatives, no prerequisites, no exclusions, and no mention of related operations. The intended usage is only implied by the action itself, which is insufficient for choosing between claim_release and other claim lifecycle 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?

Despite having no annotations, the description proactively discloses that the tool is non-mutating ('without creating or migrating absent state'), which is valuable behavioral context. It does not go further into auth or rate limits, but for a report tool this safety guarantee is a strong addition.

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 states the core action and a key behavioral qualifier. Every word earns its place; there is no filler or redundancy.

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

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

The tool has an output schema, so return values are covered, and the description gives a clear purpose and non-mutation guarantee. However, terms like 'canonical contention metrics' and 'absent state' are jargon-laden, and usage guidance relative to siblings (e.g., claim_status) is missing, leaving some gaps for an agent trying to fully understand when and how to 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?

Schema description coverage is 0%, and the description offers no explanation of the 'since' or 'repository' parameters. While the names are somewhat self-explanatory, the default '2d' and the relationship to reporting metrics are left ambiguous, and the description does not compensate for the schema's lack of descriptions.

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

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

The description uses a specific verb 'Report' with a clear object 'canonical contention metrics', immediately distinguishing it from other claim_* tools that acquire, extend, release, or reset claims. It also explicitly states what it does not do ('without creating or migrating absent state'), further clarifying its scope.

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

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

The description implies the tool is for reporting contention metrics rather than modifying state, but it does not explicitly state when to use this tool versus alternatives like claim_status or claim_acquire. No when-to-use or exclusion criteria are given, so the guidance is only implicit.

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

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

With no annotations, the description discloses the core destructive behavior ('replace' with an empty list). It also hints at a locking mechanism ('under its exact lock'), but omits side effects, permission requirements, and the full implications of the replacement.

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 compact sentence with no filler, repetition, or unnecessary details. It earns its place entirely.

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 basic operation but leaves out parameter meaning, usage context, and behavioral caveats. The output schema exists but does not compensate for missing parameter semantics and guidelines, making the tool risky to invoke without additional 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 only parameter, 'repository,' has no schema description (0% coverage) and the description does not explain its meaning or format. The phrase 'under its exact lock' may indirectly relate to the parameter but does not clarify it.

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

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

The description clearly states the action: 'Replace the live registry with an empty claim list.' The verb 'replace' plus 'empty claim list' uniquely identifies this as a reset operation, distinguishing it from sibling tools like claim_acquire or claim_release.

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

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

No explicit usage guidance or alternative tools are mentioned. The implied use case is when one needs to clear all claims, but the description does not articulate scenarios, prerequisites, or when not to use it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose one key trait: it does not create absent state, which is a side-effect guarantee. However, it omits other important behaviors such as permissions, failure modes, or what 'structured migration stop' entails, leaving significant 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 sentence with no filler words, making it concise. However, the dense jargon and ambiguous phrasing reduce accessibility, though it still earns a high score for not wasting 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?

Despite having an output schema that covers return values, the description is too terse to explain specialized domain concepts like 'primary-root claim state' or 'migration stop.' For a tool with niche terminology and a single parameter, more context is needed to make the tool actionable.

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 defines one parameter 'repository' with no description, and the tool description does not mention it at all. With 0% schema description coverage, the description was expected to compensate but fails to explain what 'repository' refers to, leaving the agent without necessary parameter semantics.

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

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

The description identifies a clear query action ('Return') targeting a specific resource ('primary-root claim state' or 'structured migration stop'), which distinguishes it from mutation siblings like claim_acquire and claim_release. However, the terms 'primary-root' and 'migration stop' are domain jargon that are not explained, slightly obscuring the tool's 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 explicit guidance on when to use this tool versus alternatives. The phrase 'without creating absent state' implies a safe read operation, but there is no mention of choosing it over claim_report or any exclusionary context.

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

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

No annotations are provided, so the description carries the full burden. It discloses meaningful behavioral constraints: source/theme paths must be absolute within workspace roots, and output defaults to the authorized server project directory. However, it does not mention side effects like overwriting existing files, required permissions, or the nature of outputs beyond the stated files.

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 then adding necessary constraints. Every sentence contributes useful information 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?

For a 7-parameter tool with a full input schema and an output schema, the description covers the primary purpose and key constraints. It lacks guidance on selecting this tool over sibling tools, but otherwise provides enough context for safe invocation regarding path boundaries and default output. The existence of an output schema reduces the need to explain return values.

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

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

Schema coverage is 100%, providing baseline 3. The description adds value by clarifying that source/theme paths must be absolute and that output_folder defaults to the authorized server project directory when null, which is not explicit in the schema. This ties the parameters together with a shared boundary rule.

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 'Create' and specifies the resource: a durable hierarchy JSON plan and its same-named HTML rendering. This distinguishes it from siblings like update_hierarchy_plan and render_hierarchy_html, which imply modification or rendering of existing plans.

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 by describing what the tool creates, and it provides path constraints ('must be absolute beneath configured workspace roots') and the default output location. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or 'when not to use' conditions.

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 carry the full burden of behavioral disclosure. It only mentions 'using the configured registry', but does not state whether the operation is read-only, has side effects, requires authentication, or how it interacts with the registry.

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

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

The description is a single sentence with no wasted words, front-loading the primary purpose. It is concise and easy to parse, though it sacrifices informational depth.

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 two required parameters and no annotation coverage, the description is insufficiently complete. It does not explain parameter relationships, expected behavior, or constraints. While an output schema exists, it does not compensate for the missing parameter semantics and behavioral details.

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 references 'project scopes' which maps to the 'scopes' parameter, but 'project_root' is completely unexplained, and no additional meaning is given for either parameter beyond the schema names.

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 ('Detect') and resource ('required technology skills for project scopes'), which clearly distinguishes it from sibling tools like skill_list or skill_find. However, the meaning of 'required' and how detection works could be more explicit, preventing a perfect score.

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

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

No guidance is given on when to use this tool compared to alternatives. The description does not mention exclusions or alternative tools, even though sibling tools occupy related skill-management functionality.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions recursion and aggregation, offering some insight, but it does not disclose side effects, access control details ('allowed folder'), or whether the operation is read-only. The behavior remains underspecified for a tool that likely accesses files or resources.

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 of about 15 words, front-loaded with the action 'Load' and the object. There is no wasted or redundant phrasing. It earns its place by stating the core purpose without unnecessary detail.

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 having only one parameter and an output schema, the description leaves significant unresolved questions: what constitutes a 'text reference,' what 'matching allowed folder' means, and how recursive aggregation behaves. Given the existence of related tools and the domain-specific terminology, this is too terse to be complete for an agent seeking to invoke it correctly.

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

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

Schema description coverage is 100%, with the sole parameter 'names' described as 'One to thirty-two unique relative paths in requested result order.' The description adds little beyond the schema, only echoing that these are 'relative paths' and that loading is 'recursive' and 'aggregated.' It does not clarify what 'names' refer to or how they map to references, but the schema already provides decent 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 'Load' and names the resource as 'recursive text references' with a scope ('every matching allowed folder'). It conveys what the tool does, though it does not explicitly distinguish it from sibling tools like reference_refresh or skill_load. The term 'text references' is somewhat ambiguous, preventing a perfect score.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or alternative tools. Sibling tools like reference_refresh and skill_load exist, but the description gives no context for choosing among them. Usage is only implied by the verb 'Load'.

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 only behavioral detail disclosed is atomicity via the word 'atomically.' With no annotations provided, the description carries the full burden of explaining side effects, permissions, idempotency, or error behavior, but it does not. This is a significant gap for a mutation-style 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 sentence that directly states the core action with no filler or redundant wording. It is highly concise and front-loaded with the essential information.

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

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

Given the complexity of an atomic refresh operation and the absence of annotations, this minimal description is insufficient. It does not explain what 'refresh' entails, when to use it, or what the output/effects are. The existence of an output schema helps slightly but does not compensate for the lack of behavioral 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 no parameters (empty schema), so there are no parameter semantics to document. The baseline for zero parameters is 4, and the description appropriately does not waste space on 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 uses the specific verb 'refresh' and clearly identifies the resource: 'project and configured user reference scopes.' This distinguishes it from sibling tools like skill_refresh (skills) and reference_load (loading references), 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?

No guidance is provided about when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent to infer when a refresh is appropriate.

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 safety constraints (path resolution, workspace authorization), default output behavior, and that inline sources avoid filesystem access. It does not detail error behavior or output formatting, but the existence of an output schema shifts some burden.

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

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

Three sentences, front-loaded with the main purpose, then precise constraints. No redundant words or filler. Each sentence adds necessary context.

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 core purpose, input flexibility, path constraints, and default output location. With an output schema present and detailed parameter schemas, this is sufficient for an agent to select and invoke the tool correctly. Minor gaps like exact error handling are not critical here.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining source accepts inline mappings/sequences/JSON/YAML or an absolute path, and clarifies path requirements for output_folder, themes_folder, and the default output directory when only a filename is given.

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

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

The description starts with 'Render safe self-contained hierarchy HTML and optionally save it' — a specific verb + resource + outcome. It clearly distinguishes this tool from siblings like create_hierarchy_plan or verify_yaml by focusing on rendering HTML.

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

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

Provides clear context about when to use: to render hierarchy HTML. It adds meaningful usage conditions (inline data require no filesystem access, paths must be absolute under workspace roots, default output location). However, it does not explicitly name alternatives or exclusions relative to 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. It adds a meaningful behavioral detail ('precedence-resolved'), which hints at resolution logic, but it does not disclose failure modes (e.g., what happens if the skill is not found) or any side effects. The schema's parameter description covers the input constraint, but the description could still mention error handling.

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, direct sentence with no filler words. It front-loads the verb and resource, making the purpose immediately clear. 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?

For a simple one-parameter tool with an output schema, the description is largely sufficient. It clearly defines the output (a SKILL.md path) and the tool's role (resolving by name). It does not need to explain return values because an output schema exists. Minor gap: it doesn't explain when a user might need this versus other skill tools, but overall it's complete for its simplicity.

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

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

Schema coverage is 100%: the single parameter 'name' is fully described as 'Exact frontmatter name in the current catalog snapshot.' The description adds no additional parameter information. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb ('Return') and resource ('SKILL.md path') with a clear qualifier ('precedence-resolved absolute') that distinguishes it from sibling tools like skill_list (which lists skills) and skill_read (which reads content). It is unambiguous and exactly what the tool does.

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

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

The description gives no guidance on when to use this tool versus alternatives such as skill_read or skill_load. There is no mention of prerequisites, typical use cases, or exclusions. The name 'find' implies locating a path, but the context is not explicitly 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 provided, the description must disclose behavioral traits. It states that the tool lists path-free metadata and related data, but does not explicitly confirm read-only behavior, side effects, or any error conditions. The lack of annotations means the agent must infer safety from the 'List' verb.

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

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

The description is a single sentence, front-loaded with the action verb, and lists the data categories without wasted words. Every part adds value.

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

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

Given the tool has zero parameters and an output schema exists, the description adequately covers what the tool does. It specifies the exact content of the list (metadata, digests, resources, shadowing counts) and the 'path-free' scope, making it complete for a listing 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 input schema has zero parameters, so the baseline is 4. The description adds no parameter-specific meaning because there are no parameters to describe. The tool's function as a listing operation is clear from the description.

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

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

The description starts with the specific verb 'List' and names the precise resources returned: skill metadata, digests, resources, and shadowing counts. The qualifier 'path-free' distinguishes this from sibling tools like skill_read or skill_find, which likely require a path or search criteria.

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 verb 'List' implies when to use this tool: to enumerate all skills without a path. However, there is no explicit guidance on when not to use it or mention of alternatives such as skill_find for targeted searches. The usage is implied rather than explicitly stated.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It mentions loading and optional extension appending, but it does not state whether the operation is read-only, requires permissions, or produces side effects. This leaves important behavioral information missing.

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 states the main action and the optional behavior with no filler or wasted words. It is appropriately 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?

The tool has a well-defined schema and an output schema, which covers parameter and return details. However, the description lacks usage guidance and behavioral transparency, creating a gap in context that is notable given the many sibling skill tools.

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

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

The schema already provides 100% parameter coverage, including clear descriptions for 'names' and 'include_extensions'. The tool description adds no additional parameter semantics beyond what is already in the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool loads skills and optionally appends extensions, using a specific verb and resource. However, it does not explicitly distinguish this from sibling tools like skill_read or skill_find, so it is not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives such as skill_list, skill_find, or skill_read. It only states the action without any exclusions or alternative tool references, leaving the agent without 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 must carry the full burden of behavioral disclosure. It mentions precedence resolution and optional extension appending, but does not explain the mechanics or potential side effects well.

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 conveys the essential function and optional behavior without any 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 large sibling toolset and the use of 'precedence-resolved' without elaboration, the description is incomplete for a newcomer to understand when and why to use this 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 100%, so baseline is 3. The description adds 'precedence-resolved' context but does not substantively enrich parameter understanding beyond the schema's own 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 uses a specific verb ('Read') and resource ('one precedence-resolved skill'), with a clear qualifier about appending extensions. It distinguishes this from sibling tools like skill_list and skill_read_resource.

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 prefer skill_read over skill_load or skill_read_resource, nor are any exclusions or alternatives mentioned. Usage context is absent.

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 explicitly states that directory traversal is not permitted, which is a meaningful security behavior. The 'read' verb implies a non-destructive operation. However, it does not mention potential error cases or authorization 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, front-loaded sentence that conveys the core action and a key safety constraint without any fluff. Every word adds value.

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

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

For a simple two-parameter tool with an existing output schema, the description covers the basic purpose and security boundary. However, it lacks parameter semantics and usage alternatives, which are important for an agent to invoke it correctly. It is minimum viable but not fully complete.

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

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

The input schema provides no descriptions for 'name' and 'resource_path' (0% coverage), and the description does not explain these parameters. It only hints via 'supporting skill resource' that the resource is tied to a skill, leaving the exact meaning of the parameters unclear.

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 ('Read') and specifies the resource type ('supporting skill resource'), clearly distinguishing it from sibling tools like skill_read which likely reads a skill itself. The additional security note about directory traversal further clarifies its scope.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like skill_read or skill_resource_load. The usage scenario is only implied by the purpose statement, with no exclusions or comparisons to sibling 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?

The description discloses atomicity ('atomically') and scope ('project and configured user skill roots'), adding value beyond a bare 'refresh'. However, it does not mention side effects, potential destructiveness, permissions, or other behavioral traits, and no annotations are present to cover these 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, efficient sentence that front-loads the action and scope. Every word contributes meaning, with no filler or repetition.

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

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

For a zero-parameter tool with an output schema, the description covers the core action and atomicity. It lacks usage context and side-effect disclosure, but given the tool's simplicity, it is reasonably complete.

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

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

The tool has zero parameters, so the schema coverage is trivially 100%. The description adds no parameter details, but with no parameters to document, the baseline of 4 is appropriate.

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

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

The description uses a specific verb ('refresh') and resource ('project and configured user skill roots'), clearly distinguishing it from sibling tools that list, find, or read skills. However, the exact meaning of 'refresh' could be more explicit (e.g., reload from disk), so it's clear but not perfectly precise.

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, or what preconditions might exist (e.g., after modifying skill files). The description only states what the tool 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?

With no annotations, the description bears full responsibility. It discloses the key behavioral traits of ordering and all-or-nothing atomicity, which is valuable. However, it does not mention potential side effects, permissions, or what happens on partial failure beyond the atomic guarantee, leaving some behavioral gaps.

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

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

The description is a single, concise sentence that is front-loaded with the core action and includes no filler. Every phrase adds meaning, making it an example of efficient specification.

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?

While there is an output schema (so return values need not be described), the description leaves out important context such as how to construct a valid request, the meaning of 'supporting resources,' and any constraints like maximum number of resources. It is sufficient for a simple tool but not fully self-contained.

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

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

Schema description coverage is 0%, and the description does not compensate by explaining the 'requests' parameter or its fields. It only hints at multiplicity with 'several,' but provides no guidance on skill_name or resource_path. The schema itself includes a brief items description, but the main description adds minimal value.

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

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

The description clearly states the action (load), the resource (supporting resources), and distinguishes from siblings by emphasizing 'several' and 'ordered all-or-nothing,' which differentiates it from single-resource loaders like skill_read_resource. However, 'supporting resources' is somewhat vague without context.

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

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

The description implies use when needing to load multiple resources atomically, but does not explicitly state when to use this tool versus alternatives like skill_read_resource for a single resource. No exclusions or alternative references are provided.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states that the tool validates names/paths without revealing side effects, return behavior, or whether it is read-only. It does not confirm that no modifications occur or what happens on invalid input, leaving significant ambiguity.

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

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

The description is a single, front-loaded sentence with no redundant wording. Every word contributes to stating the tool's purpose and scope, making it appropriately concise.

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

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

Given the tool's low complexity (one parameter), full schema coverage, and existing output schema, the description is sufficient on a basic level, but it leaves key behavioral aspects unclear, such as what exactly is validated (existence, format, accessibility) and what the result looks like. It meets the minimum viable threshold 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?

Schema description coverage is 100%, and the schema parameter description already explains that 'paths' accepts catalog names or absolute paths within configured skill roots, with snapshot precedence matching skill_find. The tool description adds minimal extra meaning beyond this, so the baseline 3 applies.

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

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

The description clearly states a specific verb ('validate') and resource ('catalog names or explicit skill paths beneath the working project'), making the tool's primary action evident. While it doesn't explicitly compare against siblings like skill_find or skill_read, the validation intent is distinct from other skill-related tools.

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

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

The description implies usage for checking whether catalog names or skill paths are valid, but it does not explicitly state when to use this tool versus alternatives such as skill_find or skill_read. There is no when-not-to-use guidance, though the scope ('beneath the working project') 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 full burden. It discloses the side effect of regenerating HTML rendering and the requirement of exactly one mutation. It does not discuss reversibility or error states, but the core mutative and rendering behavior is clearly communicated.

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

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

The description is compact and front-loaded. Four sentences cover the primary action, path prerequisites, target format, and mutation exclusivity. Every sentence adds essential information 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 complexity (7 parameters, 2 required) and the presence of an output schema, the description sufficiently covers the key operational constraints (mutual exclusion, path validation, target matching). It does not need to explain return values because the output schema exists, and the description provides enough guidance for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that exactly one of the five mutation parameters must be supplied, which the schema does not enforce. It also adds context about the plan path being beneath configured workspace roots.

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 and resource: 'Apply exactly one targeted plan mutation and regenerate its HTML rendering.' This distinguishes it from sibling tools like create_hierarchy_plan (creation) and render_hierarchy_html (pure rendering). The listed mutation types further clarify the scope.

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

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

The description provides clear context by stating the tool is for applying a mutation and lists the specific mutation types. It also gives constraints (absolute path, exact target). However, it does not explicitly name alternatives or when-not-to-use cases, 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 fully disclose behavioral traits, but it only says 'verify' without stating side effects, whether it is read-only, or what actions are taken (e.g., reporting broken links). The term 'local' hints at network independence, but key behavioral details like error handling or return semantics are absent.

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 and resource. Every word adds meaning, with no redundancy or fluff, making it highly 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?

Even though an output schema exists, the description lacks necessary context about default behavior (what happens with no patterns), what constitutes a valid target or anchor, and the precise nature of the verification. These gaps are significant given the tool's potential complexity and the absence of annotations.

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 only vaguely references 'root-relative globs,' which likely corresponds to the patterns parameter, but it does not explain the repository_root parameter or the meaning of patterns being null. The description fails to compensate for the lack of parameter documentation.

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

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

The description states a specific verb (verify), a clear resource (local Markdown targets and anchors), and a scoping mechanism (simple root-relative globs), which distinguishes it from sibling tools like verify_yaml. It is not a tautology or vague; it directly explains the tool's function.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions. While the sibling list includes verify_yaml, the description never mentions it or offers a comparison, leaving the usage context entirely implicit.

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

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

With no annotations, the description must carry the full burden. It discloses that the tool performs strict validation ('exact') and specifically checks for duplicate keys, plus returns 'structured diagnostics'. However, it omits how invalid YAML is handled (e.g., throws vs. returns diagnostics) and what 'exact' encompasses beyond duplicate keys.

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, front-loaded with the verb, and every word adds value. It avoids repetition of schema fields and is appropriately sized for the tool's simplicity.

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?

While an output schema exists (so return format is covered), the description does not explain the interaction between paths and repository_root, nor the precise validation semantics. It is moderately complete for a simple validation tool but leaves enough ambiguity to warrant a mid-range score.

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

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

Schema coverage is 0%, and the description does not explain the roles of 'repository_root' or 'paths'. It only implies that paths point to YAML files, leaving critical ambiguity about whether paths are relative to repository_root or absolute, and how the validation resolves 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 clearly states the tool validates YAML files, using the verb 'Validate' with the resource 'YAML files'. The specific mention of 'duplicate keys' and 'structured diagnostics' adds precision, distinguishing it from sibling tools like verify_markdown_links and skill_validate.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. While the name suggests YAML validation, there is no mention of when not to use it or citations of other tools for different file types. The context is implied but not stated.

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