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

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description goes beyond annotations by explaining what each output mode actually yields ("standalone" = full HTML doc with base styles ready to open; "raw" = original markup captured from theknowledgehouse.org), which is genuinely useful behavioral context.

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

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

Front-loaded with the core action, then a dense but efficient enumeration of formats. The single run-on sentence is information-rich with little waste, though the format list could be broken up for readability.

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

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

With no output schema, the description carries the return-value burden and does so by describing what each format produces. Gaps remain around invalid-name behavior and how to discover available props, but for a read-only single-item getter this is largely 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 description coverage is only 33%, so the description has to compensate and largely does: it defines every format value including the default ("bundle") and the special semantics of "standalone" and "raw", which the bare enum cannot convey. The props parameter is only lightly covered ("override the default content"), leaving some gap.

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

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

States a specific verb+resource ("Get one component") and clearly signals single-item retrieval, which distinguishes it from list_components and search_components without naming them. It falls short of a 5 because it never explicitly contrasts itself with those 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?

Usage is implied rather than stated: the format enumeration and the note to pass props convey how to call it, but there is no explicit when-to-use-this-vs-alternatives guidance (e.g., versus get_design_spec or render_page). A reader must infer the context from the sibling names alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses the breadth of the payload (layout, typography, colors, interactions, responsive rules), but says nothing about output format (markdown vs structured), size, or whether it is scoped only to the homepage. With annotations carrying the behavioral baseline, this is adequate but thin.

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 sentence, front-loaded with the resource and followed by a compact enumeration of what it contains. The parenthetical list is dense but earns its place; 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?

For a parameterless, read-only retrieval tool with no output schema, the description covers what is returned and its scope. The only gap is the return format, which an agent might want to know when planning how to consume the spec, but this is minor for a simple getter.

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. The description correctly implies no input is required, and there are no parameters whose semantics could be missing.

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

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

The description names a specific resource — the full written UI/UX specification of theknowledgehouse.org's homepage — and enumerates its contents (layout, typography, colors, interactions, responsive rules), so an agent knows exactly what it retrieves. It does not explicitly distinguish itself from get_design_tokens or get_site_content, but the 'full specification' framing implies broader coverage than tokens alone.

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 when-to-use guidance, no statement of prerequisites, and no routing to or away from siblings such as get_design_tokens (which presumably returns the token subset) or get_site_content. The scope is implied by the content description, but the agent must infer when this tool is preferable to the other design-related 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that tokens are 'measured from the live site,' which is meaningful provenance context, but says nothing about freshness, caching, or auth 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?

Two dense sentences, front-loaded with the resource and provenance, then the format options. Every clause earns its place, though the parenthetical lists are packed tight.

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

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

With no output schema, the description must convey returns, and it does via the per-format breakdown of what each mode produces. It is largely sufficient for a single-parameter read tool, lacking only freshness or caveat notes.

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% for the single format parameter, so the description carries the full burden and does — explaining that 'json' is the default, 'css' yields CSS custom properties only, and 'base-css' adds global styles, ripple buttons, and reveal animation. This is exactly the meaning the bare enum lacks.

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 resource (design tokens) and its provenance (measured from the live site), enumerating the token categories covered (colors, type scale, spacing, layout, motion, scrollbar). An agent can tell this retrieves design tokens rather than components or page content, though it never names siblings like get_design_spec to sharpen the distinction.

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 statement of when to prefer this over get_design_spec, get_site_content, or the component tools. The format values imply different output contexts, but there is no explicit when-to-use or when-not-to-use 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?

readOnlyHint=true already establishes that this is a safe read, so the bar is lower. The description adds genuine value by disclosing the returned payload's structure, which matters because there is no output schema. It does not mention freshness, caching, or whether the scraped content can go stale.

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

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

Two sentences, front-loaded with the payload contents before the practical usage hint. The long parenthetical list is dense but earns its place given the absent output schema.

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

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

With no output schema and no parameters, the description carries the burden of describing what comes back, and it does so item by item. Minor gaps remain around content freshness and whether the shape is stable, but an agent has enough to call this 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 the baseline is 4. There is nothing parameter-related for the description to clarify, and it correctly spends no words on inputs.

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 verb+resource (retrieving structured homepage content) and enumerates exactly what that content contains (nav tree, announcement, mission, pillars, testimonials, news, footer links, social, badges). It is precise about scope, though it never distinguishes itself from siblings like get_component or render_page.

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?

'Useful as a template for your own props' implies one intended use case, which gives some guidance. However, there is no explicit when-to-use vs. when-not, no mention of sibling tools, and no prerequisites, so the agent must infer the rest.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds valuable context by enumerating the fields returned (name, title, category, description, prop names), which matters since no output schema exists. It doesn't cover pagination or result-volume 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?

Two tight clauses with the core action and its return payload front-loaded, then the optional filter. Every word earns its place with no redundancy.

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

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

For a simple read-only listing tool with annotations covering its safety profile and the return fields named, the definition is essentially complete. Only minor gaps remain, such as result volume or how results are ordered.

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 single category parameter lists its allowed values in the schema, so the schema carries the semantics. The description only restates that the filter is optional, adding little beyond what's already documented.

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 gives a specific verb+resource ('List every saved TKH component') and even enumerates the returned fields, so its purpose is unambiguous. It does not explicitly distinguish itself from the sibling search_components, so it falls short of a 5, but a reader can infer the difference between a full listing and a search.

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?

'Optionally filter by category' implies the usage context (browse all when unfiltered, narrow when a category is known), but there is no explicit when-to-use statement or reference to alternatives like search_components for targeted lookups. Usage is left to inference.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description usefully explains the non-read side effect: it only writes when outputPath is set. It also adds real behavioral context (dedupe of per-component CSS/JS, base styles, font). However, it never addresses whether an existing file at outputPath is overwritten, which is the key risk for this mutation, so it stops short of full transparency.

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

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

Three short sentences, front-loaded with the core action, then defaults, then the optional write. Every clause carries information; nothing is redundant 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?

No output schema exists, and the description implicitly conveys a return value (the composed HTML, unless written to disk). Combined with the defaults and the dedupe/composition notes, an agent has enough to call it. The unaddressed 'title' parameter and overwrite semantics keep it from being 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 75%, so most parameters are already documented in the schema (extraCss, sections default array, outputPath). The description largely restates those ('sections defaults to the full homepage order', 'optionally write the result to outputPath') and leaves 'title' unexplained in both places. Baseline 3 applies when 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?

States a specific verb and resource ('compose components into one standalone HTML page') plus the concrete output traits (base styles, Lato font, deduped CSS/JS). This is clearly distinct from the read-oriented siblings (get_component, list_components, get_design_tokens), so an agent can route to it without ambiguity.

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

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

The description never says when to call this versus gathering components with the sibling tools, nor what prerequisites exist (e.g. components must first be resolved). It mentions the sections default, which is parameter behavior rather than usage guidance. No exclusions or alternatives are 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?

readOnlyHint=true already establishes this as a safe read, so the description's added value is limited to the fact that matching spans multiple fields rather than just names. It says nothing about result limits, ordering/relevance, or pagination behavior, all of which matter for a search 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?

One sentence, front-loaded with verb+resource, with the searchable-field list and inline examples folded in without any filler.

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

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

For a one-parameter, read-only search with no output schema, the description is nearly sufficient: purpose, scope of matching, and query examples are covered. Only the shape of results (fields returned, ranking, limits) is left unstated, which is a minor gap 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 0% and the single query parameter is an undescribed string, so the description carries the load — and it does so by explaining which fields the keyword matches against and giving concrete example terms ("slider", "dropdown", "cards"). That meaningfully clarifies how to phrase the argument beyond the bare type.

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 (keyword search) and resource (components), and enumerates the searched fields (names, descriptions, categories, props), which plainly separates it from get_component. It never names a sibling or scope difference explicitly, so it stays 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 only implied: the word 'search' plus query examples signal lookup-by-keyword, but there is no guidance on when to prefer this over list_components or get_component, nor any note on exclusions such as empty results or exhaustive listing.

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