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

With no annotations, the description carries the full burden and does well: it discloses the return capture (exit code, stdout, stderr, duration, _site path) and the timeout ceiling (default 120s). It does not state permission/prerequisite requirements or what happens on failure beyond captured exit code, preventing a 5.

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?

Five tight sentences, each carrying a distinct fact (command form, outputs captured, exclusions, when to use, timing). Front-loaded with purpose and no filler.

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

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

For a build tool with no output schema, the description covers what is returned, timing, and constraints. Missing only failure-mode detail (e.g., what a non-zero exit implies or partial-build behavior) to be 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?

Schema coverage is 100% for the single 'clean' parameter, so baseline is already 3. The description adds meaningful context about how the build command is formed (Gemfile detection) and does not merely repeat the schema, earning a modest bump.

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?

States a specific verb+resource ('Run a Jekyll build') and even clarifies the exact command variant (bundle exec when Gemfile present). It is clearly distinguished from sibling tools like jekyll_validate and jekyll_doctor, which serve different verification purposes.

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

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

Explicitly says when to use it ('after creating or modifying components to verify the site builds') and what it is not for ('Does not accept arbitrary shell commands'). This routing guidance is unusually complete.

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

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

No annotations are provided, so the description carries full behavioral burden. It discloses that the operation modifies project files, supports dry_run, and normalizes names to kebab-case, but it does not state overwrite/collision behavior, required permissions, or what happens on failure. Those gaps matter for a file-creating 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?

Four short sentences, front-loaded with the core action and followed by routing, side-effect, and normalization notes. No filler or repetition.

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

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

Given a 7-parameter create tool with no output schema and no annotations, the description covers purpose, usage boundaries, mutation, dry_run, and naming normalization. It is mostly complete, though it omits collision/overwrite behavior and return semantics.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful semantic detail beyond the schema: names are normalized to kebab-case, which is not stated in the schema’s examples.

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?

States a specific verb (Create) and a specific resource (reusable Jekyll Liquid component plus associated SCSS, documentation, and example files). It distinguishes this packaged create from siblings like jekyll_scss_create and jekyll_docs_create, which create individual artifacts.

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?

Gives an explicit when-to-use condition ('when the user asks to create a new reusable UI component') and an explicit when-not condition ('Do not use for one-off page markup'). It does not name a specific alternative tool for one-off markup, so it stops short of the highest tier.

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

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

With no annotations, the description carries the full burden and does well: it flags DESTRUCTIVE in caps, enumerates the file types destroyed, and states the two gates (confirm flag, full-write mode). It omits irreversibility and permission/rollback detail, but the destruction scope is unusually well disclosed.

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

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

Three tight sentences, front-loaded with the action and destruction warning. 'Prefer dry reasoning before calling' is slightly vague and is the only clause that does not fully earn its place.

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

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

For a destructive two-parameter tool with no annotations and no output schema, the definition covers scope, safety gates, and mode prerequisites. Missing only irreversibility and any note on return/error behavior, which are minor given the description's density.

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 50%: 'confirm' is documented in the schema as 'Must be true to proceed', and the description reinforces that. The 'name' parameter has no schema description and the description never clarifies what identifies the component, so the low-coverage gap is only partially compensated.

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?

States a specific verb (Delete) and resource (component) and enumerates the exact artifacts removed (Liquid, SCSS, JS, docs, example). This clearly separates it from siblings like jekyll_component_create, jekyll_component_get, and jekyll_component_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?

Gives concrete preconditions (confirm: true, full-write mode) and a caution to reason dry before calling. It does not name an alternative flow (e.g., validate or get before delete), so it stops short of explicit when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. It does add the critical behavioral claim 'Read-only', which is genuinely useful. However it doesn't describe error behavior for a missing component name, normalization side effects (schema covers this) or output format details. Adequate but thin for a read operation with no annotations.

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

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

Three tight sentences: what it returns, when to use it, and its safety profile. Front-loaded with the action and payload; no filler.

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

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

Complete enough for a simple single-param read tool: purpose, payload contents, usage timing, and read-only nature are all covered. Minor gap is that with no output schema the description enumerates fields but doesn't note structure/formatting of the source payloads.

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 there is only one parameter whose schema description already explains normalization ('any case/spacing; normalized to kebab-case'). The description adds no syntax or format detail beyond the schema, so 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?

Specific verb+resource: 'Get full details for one component by name'. Explicitly enumerates the returned payload (Liquid/SCSS/JS/docs source, detected parameters, variants, accessibility notes, class names), distinguishing it from jekyll_component_list (plural) and from create/validate/delete siblings.

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?

States when to use it ('before editing or reviewing a component') which implies the workflow relationship with jekyll_component_create/validate. But does not name the alternative (e.g. jekyll_component_list for browsing all components) or state exclusions explicitly.

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 behavioral burden, and it does address the key trait ('Read-only') plus the scope of the scan ('all detected'). It does not cover pagination, ordering, or what 'detected' is relative to (e.g. requires a prior scan), which are the remaining 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?

Three short sentences, front-loaded with the core action and return shape, then usage, then safety. No filler or restatement 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?

For a zero-parameter, no-output-schema list tool this is close to sufficient: it says what is listed, what each entry exposes, when to use it, and that it is non-mutating. Minor omissions are whether results are paginated or ordered and any dependency on a prior project scan.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Schema coverage is 100% and the empty object schema is self-explanatory.

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?

States a specific verb and resource (list reusable components) and describes the shape of what comes back: paths to Liquid, SCSS, JavaScript, docs and examples. It reads as distinct from jekyll_component_get by virtue of 'list all', though it never names that sibling explicitly.

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?

'Use to discover existing components before creating new ones' gives clear situational context and ties the tool to the jekyll_component_create workflow. It stops short of naming jekyll_component_get as the alternative for a single known component, so no explicit exclusion is 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 and does reasonably well: it declares the operation is read-only and states that it returns structured errors and warnings. It does not describe severity semantics beyond 'errors and warnings', whether validation is partial (e.g., stops at first failure), or what happens for a nonexistent component, but for a low-risk read-only check this is largely adequate.

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

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

Two sentences, both information-dense: the first front-loads the enumerated checks, the second covers return shape and the read-only guarantee. No filler, no restatement 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?

For a single-parameter, no-annotation tool with no output schema, the description covers what is checked, that output is structured errors/warnings, and that it is read-only. The main omission is when this tool should be preferred over the sibling validators, which is the only thing an agent is still missing.

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?

There is one parameter ('name') with 100% schema description coverage, so the schema already documents it. The description adds no format hints (e.g., does it accept a path, a slug, or a nested component path), so the baseline 3 for schema-covered parameters 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 pairs a specific verb (validate) with a specific resource (a component) and even enumerates the check categories performed: file existence, Liquid syntax, SCSS presence, documentation, accessibility hints, parameter consistency. Scope (single component) implicitly separates it from the project-level jekyll_validate and jekyll_doctor, though those siblings are never named.

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

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

There is no explicit guidance on when to invoke this tool versus jekyll_validate, jekyll_doctor, or jekyll_build, all of which could plausibly overlap. The only usage signal is the implicit 'validate one component', leaving the agent to infer pre-edit vs post-edit timing and the boundary with the project-wide validator.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses redaction of sensitive keys, explicitly promises no API keys/tokens/credentials are returned, and states 'Read-only'. It stops short of describing which config files are merged or their precedence order, but the safety-relevant behavior is unusually well covered.

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 short sentences, front-loaded with the action and resource, then the redaction guarantee, then the read-only nature. No filler and every clause carries 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?

For a zero-parameter read tool with no output schema, the description gives enough to call it correctly and anticipate redacted results. It does not explain how multiple config files (e.g. _config.yml plus environment overrides) are combined, which is a minor gap.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. The description adds nothing parameter-related, but nothing is needed.

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

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

States a specific verb and resource ('Read Jekyll configuration (_config.yml etc.)') and immediately adds the distinguishing qualifier that output is redacted. This separates it cleanly from siblings like jekyll_project_info or jekyll_project_scan, which serve different purposes.

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

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

'Use to understand site settings' gives an implied context for invoking the tool, but there are no explicit when-not conditions and no named alternatives among the many jekyll_* siblings. The usage guidance is present but minimal.

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 behavioral burden; it usefully discloses 'Modifies project files' and that dry_run exists, which an agent needs to know before calling. However, it omits whether existing docs are overwritten, where files land, or what permissions are required.

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 terse sentences, front-loaded with the core action and sections, then the mutation side effect, then the dry_run option. No filler.

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

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

For a 5-parameter mutation tool with no annotations, no output schema, and 20% schema coverage, the description covers the essentials (what is created, that files change, dry_run) but leaves dry_run semantics and overwrite behavior unexplained.

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 20% (only 'name' is documented), so the description must compensate. It names the documentation sections that map loosely to overview/variants/parameters, but says nothing about the 'name' or 'dry_run' parameters' expected values, leaving real gaps.

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?

States a specific verb+resource ('Create component documentation') and enumerates the exact sections produced, which is far more informative than the bare name. It does not explicitly distinguish itself from the sibling jekyll_docs_update, though the create/update split is inferable from the names.

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 on when to use this versus jekyll_docs_update or jekyll_component_create, and no prerequisites stated. 'Supports dry_run' hints at a preview workflow but never says when to prefer 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 full burden, and it does disclose meaningful traits: it modifies project files, it auto-fills gaps from detected Liquid parameters, and it supports dry_run as a preview mechanism. However, it omits overwrite semantics, permission requirements, and what happens to existing content that isn't in the new input.

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?

Four short, front-loaded sentences with no filler; the mutation and dry_run facts are stated plainly. Minimal but efficient, with no wasted text.

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 mutation tool with no annotations, no output schema, and 0% parameter documentation, the description is far too thin. It should at minimum explain the input fields, overwrite behavior, and the create-vs-update boundary.

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% across 7 parameters, so the description must compensate, and it barely does. It only clarifies dry_run; name, notes, overview, variants, parameters, and accessibility are left entirely unexplained in both schema and 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?

States a specific verb and resource ('Update or regenerate documentation for a component'), clearly a mutation of an existing docs artifact. It does not name the obvious sibling jekyll_docs_create, so the agent must infer the update-vs-create split, but the purpose itself 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?

No when-to-use guidance and no distinction from jekyll_docs_create or from the other update-style siblings. The clause 'Fills gaps from detected Liquid parameters when possible' hints at behavior but does not tell the agent when to choose this tool over regenerating by other means.

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 does disclose one meaningful trait: "Read-only regarding project source files," which reassures the agent it won't mutate content. However, it says nothing about whether any cache/artifact files are written, what permission or environment prerequisites exist, or how results 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?

Two short sentences with no filler. The action and scope are front-loaded, and the safety note is placed second where it reads as a qualifier rather than drowning 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?

For a zero-parameter diagnostic with no output schema and no annotations, the description covers what it does and one key behavioral trait. It is close to complete; a note on what the diagnostics look like or the expected environment would close the remaining 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 tool takes zero parameters, so the baseline is 4 and there is nothing for the description to document or compensate for. No parameter semantics gap exists.

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?

States a specific verb and resource: "Run jekyll doctor to check for common configuration and environment issues." This separates it from build/validate siblings by naming the diagnostic scope (config + environment). It does not explicitly differentiate against jekyll_validate or jekyll_project_scan, which are the nearest neighbors.

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

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

The description implies usage context (troubleshooting configuration and environment problems), but gives no explicit "use this when / use X instead" guidance or prerequisites, such as needing to be run inside a Jekyll project root. An agent must infer the trigger condition from the one-line purpose statement.

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 present, the description carries the full burden and does reasonably well: it declares 'Read-only' and 'Never executes Liquid,' which is meaningful safety context for a templating include, and it previews the return content (source, front matter, parameter analysis, syntax checks). It stops short of describing error behavior for a missing include or any path-resolution rules.

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 short sentences, front-loaded with the action and resource, followed by return contents and the safety constraint. No filler, and the important boundary ('Never executes Liquid') is given its own sentence rather than buried.

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?

No output schema exists, so the description correctly compensates by enumerating the return fields, and it covers the read-only/non-executing behavior. The only gap is failure semantics when the include name does not resolve, which an agent calling a lookup-by-name tool would benefit from knowing.

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

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

Schema coverage is 100% and the single parameter's schema description ('Include name or relative path') is essentially duplicated in the description text. Baseline 3 applies since the schema already does the work and the description adds no format or resolution detail.

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?

States a specific verb ('Read') and resource ('a Liquid include') plus the lookup key ('by name or relative path'). The sibling set contains jekyll_include_list, so the singular 'Read a Liquid include' cleanly differentiates this single-item retrieval tool from the listing 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?

Usage is only implied: an agent can infer this fetches one include versus jekyll_include_list enumerating them, but the description never says when to prefer it or what happens if the named include does not exist. No explicit alternatives or exclusions are given.

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

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

With no annotations, the description carries the full burden and does address the two salient risks for a Liquid-facing tool: it is read-only and it never executes Liquid. It omits return shape and ordering, but for a zero-parameter enumeration the safety profile is the material disclosure.

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 short sentences, front-loaded with the scope, then the exclusion, then the safety note. No filler and every clause carries 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?

For a no-param, no-output-schema listing tool this is close to complete: scope, exclusions, and behavioral guarantees are all present. A note on what the returned entries look like (paths vs names) is the only real 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 tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming the unfiltered nature of the listing. Baseline 4 applies.

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

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

States a specific verb (List) and resource (Liquid includes) with the exact location (_includes), and carves out the components/ and sections/ subtrees by naming the dedicated tools that own them. An agent can distinguish this from jekyll_include_get and jekyll_component_list without opening any schema.

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 exclusion clause effectively routes the agent: if you want components/ or sections/ includes, use the dedicated tools instead. That is clear context, though it never explicitly says when to reach for jekyll_include_get versus this list 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, the description carries the full burden and does add real behavioral context: it declares the operation read-only and states that Liquid is never executed, which is a meaningful safety disclosure. It omits error behavior for missing layouts and any path restrictions, so it is not exhaustive.

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

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

Three short, front-loaded sentences with zero filler: what it reads, what it returns, and the safety constraint. Every sentence 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?

There is no output schema, so the description correctly compensates by naming the return payload (source, front matter, analysis). Combined with the safety note, an agent has what it needs, though nothing is said about not-found handling.

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% for the single 'name' parameter, so the schema already documents that it accepts a name or relative path. The description restates this without adding format, extension, or resolution semantics, 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?

States a specific verb (Read), a specific resource (Liquid layout), and the lookup key (name or relative path), which cleanly separates it from the sibling jekyll_layout_list.

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

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

The description implies usage by specifying that a name or relative path is required, and the read-only framing hints at a safe inspection step. It never explicitly says when to use this versus jekyll_layout_list or jekyll_component_get, so guidance stays implied.

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

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

No annotations are provided, so the description carries the full safety burden, and it does address the key risk: 'Read-only. Never executes Liquid.' reassures the agent that inspecting layouts will not evaluate template code. It omits return shape, ordering, or error behavior, keeping it below a 5.

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 very short sentences, none wasted, with the core action front-loaded and the safety caveat immediately after.

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-argument, read-only listing tool with no output schema, the description covers action, scope, and the one meaningful behavioral risk. Only minor gaps remain, such as what the listing returns or whether it recurses.

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 takes zero parameters, so there is nothing for the description to disambiguate; the empty schema is self-explanatory. Baseline 4 applies.

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

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

States a specific verb ('List') and resource ('Liquid layouts') and scopes it to the `_layouts` directory, which cleanly separates it from the sibling jekyll_layout_get. It doesn't explicitly name that sibling as the alternative, so it stops short of a 5.

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

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

Usage is implied rather than stated — an agent can infer this is the discovery call for layouts, but the description gives no when-to-use framing, no mention of when to prefer jekyll_layout_get, and no prerequisites (e.g., must a project be initialized).

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

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

With no annotations provided, the description carries the burden and does disclose two important behavioral traits: 'Does not modify any files' (read-only safety) and 'Never exposes secrets' (security posture). This is meaningful beyond schema, though it omits any detail on error behavior or the meaning of the cryptic 'write mode' field.

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 short sentences, front-loaded with the tool's output scope before the usage cue and the two safety guarantees. Every clause carries information and there is no padding 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 info tool with no output schema, the description compensates well by enumerating the returned summary fields and stating the read-only/security guarantees. The one gap is that 'current write mode' is left unexplained, but overall the agent has enough to call and interpret the tool correctly.

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

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

The tool takes zero parameters, so there is no parameter surface for the description to clarify; the calibration baseline for a zero-param tool is 4. Nothing is contradicted or left ambiguous in the parameter dimension.

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 and resource ('Return a high-level summary of the Jekyll project') and then enumerates exactly what the summary contains (site status, layout/include/component counts, SCSS/JS/docs presence, write mode). This aggregate framing makes it functionally distinguishable from per-resource siblings such as jekyll_layout_list and jekyll_component_list without opening either schema.

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 gives an explicit routing cue, 'Use this first to orient yourself,' which tells the agent when to reach for this tool in the workflow. It does not, however, name any alternative tool or state when-not to use it, so it falls short of full when/when-not guidance.

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

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

With no annotations present, the description carries the full burden. It discloses one important trait, 'Read-only,' which tells the agent this is a safe inspection call. Beyond that it is silent on caching behavior (the force param implies a cache exists), cost, or freshness of the scan, leaving real gaps for a no-annotation 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?

Two sentences, zero filler. The return payload is front-loaded, followed by the triggering condition and the safety note. Every clause 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?

There is no output schema, and the description compensates by enumerating the map's contents so the agent knows what it will receive. Combined with the usage trigger and read-only note, this is nearly complete; only caching/freshness semantics are unaddressed.

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?

There is a single parameter and schema description coverage is 100%, so the schema already explains 'force' as a cache bypass. The description adds no parameter-level guidance, which is acceptable at this coverage level but earns no extra credit.

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?

States a specific verb (scan) and resource (the project), and enumerates exactly what the returned architecture map contains (config files, directories, layouts, includes, components, sections, SCSS/JS). This distinguishes it clearly from narrower siblings like jekyll_project_info or jekyll_config_get, which return subsets.

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

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

Explicitly says when to reach for it: 'when you need a detailed map before creating or modifying components.' That is a clear triggering context. It does not, however, name alternatives (e.g., project_info) or state when not to use it, so it falls short of the 5 bar.

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 does disclose the key traits: it mutates project files, writes into the configured SCSS tree, and supports a dry_run preview, plus that a stub is generated when content is omitted. It omits overwrite/collision behavior, permission requirements, and error semantics for an existing 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?

Four short front-loaded sentences with no filler; the purpose leads and the write-location and dry_run facts follow. Slight redundancy between 'Writes under the configured SCSS tree' and 'Modifies project files' keeps it from a 5.

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 mutation tool with no annotations and no output schema, the description covers destination and dry_run but leaves overwrite behavior, validation failures, and required permissions unstated. Adequate but with clear gaps.

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

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

Schema coverage is 75% and the schema already documents name, content, and category. The description only adds that dry_run is supported, without explaining its effect; the remaining parameter meaning lives in the schema. Baseline 3 is appropriate.

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

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

Specific verb (Create) + resource (new SCSS partial), with clarifying examples and the write location ('under the configured SCSS tree'). An agent can distinguish this from jekyll_scss_list and jekyll_scss_get without opening a schema.

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 when-to-use or when-not-to-use guidance and no alternatives named. 'Supports dry_run' hints at a preview workflow but never says when to prefer dry_run or what happens if the partial already exists.

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 present, the description carries the burden and does declare 'Read-only' plus the shape of what is returned (source plus parsed analysis). It omits failure behavior for missing/invalid paths and any size or performance caveats, which would round out the behavioral picture.

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

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

Two sentences, zero filler, with the action and return contents front-loaded and the path constraint following. Every clause conveys distinct 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?

For a single-parameter read tool with no output schema, the description adequately covers input semantics, read-only nature, and the returned payload. Only error/edge-case behavior on a nonexistent path is unaddressed.

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

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

The schema already documents the single 'path' parameter at 100% coverage, so the baseline is 3. The description adds real meaning beyond the schema by specifying the path is relative to the project root and by naming the sibling tool that produces valid values.

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?

States a specific verb and resource ('Read an SCSS file') and enumerates exactly what the response contains (imports, variables, CSS custom properties, mixins, selectors). This clearly separates it from jekyll_scss_list (enumeration) and jekyll_scss_create (writing).

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?

Gives concrete invocation context: supply a path relative to the project root, and obtain that path from jekyll_scss_list, which routes the agent to the right sibling. It does not state when NOT to use it or what happens if the file is absent, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses 'Read-only' and enumerates the layer categories it detects, which is meaningful behavioral context. However it says nothing about the return shape, whether detection is heuristic, or how large projects are handled, leaving gaps for a zero-annotation 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?

Three short clauses, front-loaded with the action and scope, followed by the usage condition and the read-only guarantee. Every clause earns its place and nothing is padded.

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, read-only listing tool with no output schema, the description covers purpose, usage context, safety profile, and the categories returned. It is nearly complete; only the concrete return format is left implicit.

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 takes no parameters, so the baseline is 4; there is nothing for the description to compensate for. The parenthetical layer list describes output categories rather than inputs, adding no parameter meaning but causing no harm.

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?

States a specific verb and resource ('List SCSS/CSS files under the project SCSS root') plus an additional capability (detecting architecture layers), which cleanly separates it from jekyll_scss_get and jekyll_scss_create. An agent can distinguish it from all siblings without opening a schema.

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?

'Use to understand stylesheet structure before editing' gives a clear when-to-use condition tied to the editing workflow. It does not name alternatives (e.g. jekyll_scss_get for reading a single file), so it falls short of explicit routing, but the context is unambiguous.

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

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

With no annotations provided, the description carries the full behavioral burden. It does disclose 'Read-only', which is the key safety signal, but omits return shape (single token vs. list) and pagination behavior. The read-only disclosure is valuable given absent annotations, but disclosure is thin overall.

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

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

A single front-loaded sentence plus a two-word safety note. Every element earns its place with no padding.

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 one-parameter read lookup with no output schema, the description covers purpose, input semantics, and read-only safety adequately. The only missing piece is the return format, but the simple shape of the tool makes that a minor gap.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds concrete examples ('color', 'spacing', '--color-primary') that materially clarify what a name fragment or category looks like beyond the schema's terse 'Token name fragment or category'.

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?

States a specific verb (Get) and resource (tokens) with scope (matching a name or category), so the verb+resource pairing is unambiguous. It does not, however, distinguish itself from the sibling jekyll_token_list, which an agent could easily confuse with a filtered lookup.

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?

'Matching a name or category' implies when the tool is appropriate, but there is no explicit guidance on when to use this versus jekyll_token_list, nor any stated exclusions or prerequisites. Usage is inferred rather than directed.

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

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

With no annotations provided, the description carries the full burden, and it does disclose the key safety trait ('Read-only') plus the categorization behavior of the result. However, it says nothing about whether it scans the project root, whether results are grouped/sorted, or how large a token set it returns, leaving meaningful behavioral gaps for a scan-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?

A single front-loaded sentence that names the verb, resource, scope and categories, with 'Read-only' as a short trailing tag. Nothing is padded or repeated.

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

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

For a zero-parameter, no-output-schema read tool, the description covers purpose, scope and the categories returned, which is close to sufficient. It could still note that it reflects the scanned project and whether an empty result means no tokens were found, but nothing essential is missing.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The categorization list adds minor interpretive value about result shape rather than parameter meaning.

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?

States a specific verb (List) and resource (design tokens discovered in SCSS) and clarifies the two token flavors (CSS custom properties and Sass variables). It is clearly distinguishable from jekyll_scss_list and jekyll_token_get/update, so an agent can select it without opening any schema.

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

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

The description implies when this tool is useful (discovering existing tokens) but never states it explicitly, nor does it name alternatives or exclusions relative to jekyll_token_get or jekyll_scss_list. Usage must be inferred from the purpose statement.

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 usefully discloses that it modifies project files and supports dry_run, but does not explain what happens when the token is absent (append vs overwrite), reversibility, or any permission/confirmation 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?

Three short, front-loaded sentences with no filler; the core action leads and the dry_run note trails. Efficient, though each sentence is terse enough to leave gaps.

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 file-mutating tool with no annotations and no output schema, the description covers the mutation and dry_run but omits the append-vs-update distinction, path resolution, and error/return behavior an agent would need to invoke it confidently.

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 75%, with the required file/name/value documented in the schema. The description adds only that dry_run is supported, without clarifying its behavior (preview vs no-op), so it does not meaningfully exceed the schema baseline.

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?

States a specific verb+resource ('Update or append a design token declaration in an SCSS/CSS file') and clearly distinguishes it from siblings like jekyll_token_list and jekyll_token_get. The 'update or append' phrasing leaves the exact mutation semantics ambiguous, keeping it short of a 5.

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

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

No guidance on when to use this versus jekyll_token_list/get or a potential create tool, and no prerequisites stated. 'Prefer CSS custom properties' is a format preference, not a when-to-use condition.

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

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

With no annotations, the description carries the full burden and does deliver real value: it declares the operation safe, states it does not execute arbitrary shell, and notes the return shape (structured errors and warnings). It omits the slower run_build side effect of writing build output and any permission prerequisites.

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 tight sentences, front-loaded with the verb and scope, then the checks, then the return contract and safety caveat. Every clause earns its place with no filler.

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

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

For a single-optional-param tool with no output schema, the description covers what is validated, the return shape (errors and warnings), and the safety boundary. The main gap is the absence of routing guidance among the many validation-adjacent siblings.

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% for the single optional boolean, so the baseline is 3. The description adds only a mild hint ('optional Jekyll build') that maps to the same parameter the schema already documents, adding no syntax or format detail.

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?

States a specific verb ('validate') and resource scope ('project-level'), enumerating what is checked: component structure, Liquid patterns, front matter. It implicitly separates itself from the component-scoped sibling jekyll_component_validate, though it never names that sibling explicitly, which keeps it short of a 5.

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

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

Usage is implied rather than stated: an agent can infer this is the broad pre-flight check, but the description never says when to prefer it over jekyll_doctor, jekyll_build, or jekyll_component_validate. 'Optional Jekyll build' hints at the build relationship but stops short of routing guidance.

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