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

No annotations are provided, so the description must carry the full behavioral burden. It discloses the comparison mechanism, the live-vs-cached nature, and the kind of results reported. However, it does not explicitly state whether the operation is read-only, whether it performs network access, or what the exact return shape is. This is acceptable but not richly transparent.

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

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

Two sentences with no filler. The core behavior is front-loaded, and the second sentence adds a valuable scope limitation. Every word earns its place.

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

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

For a tool with one optional parameter and no output schema, the description covers the main behavior and constraint. However, it leaves ambiguity about what happens when 'known' is omitted, and it does not describe the return format beyond 'reporting brands'. Adequate 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%, so the parameter 'known' is already documented as an optional map of slug to sha256. The description adds context by linking this to the notion of 'cached' state and 'published sha256', which reinforces the semantics but does not add substantial new meaning beyond the schema.

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

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

States a specific action ('Compare getdesign.md's live signed index against what is cached') and a precise outcome ('reporting brands that are new or whose published sha256 changed'). This clearly distinguishes it from sibling retrieval and installation tools, and the restriction to getdesign.md further narrows 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 gives clear context for when this tool applies: when checking for catalog updates via digest comparison. It also states a limitation ('Only getdesign.md publishes digests, so only it can be checked this way'), which helps an agent avoid misapplying it to other providers. It does not name specific sibling alternatives, but the context is sufficient.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It usefully reveals the large average size (~8k tokens) and that sections are typically under 10% of the file, making the cost tradeoff transparent. It does not discuss errors or return format, but the core behavior is clear.

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 concise sentences deliver the key information up front: what is returned, the preferred mode, and the cost-based reason. Every sentence 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 simple read tool with full schema coverage and no output schema, the description explains both the return value and the key usage consideration. It is slightly incomplete in not addressing siblings like get_design_sections, but the core calling context is sufficiently covered.

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 parameters are already documented. The description adds important practical meaning by recommending the `section` parameter be used almost always, effectively clarifying that `section` is optional in schema but strongly preferred in practice.

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

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

The description clearly states what the tool does: return a DESIGN.md file, or preferably one section of it. This is specific enough to distinguish the core operation, though it does not explicitly differentiate itself from siblings like get_design_sections or get_project_design.

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 explicit, actionable guidance: always pass `section` unless the whole document is genuinely needed, with a concrete token-cost rationale. This is exactly the kind of when-to-use guidance an agent needs.

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 behavioral disclosure burden. It discloses that the tool returns only section sizes rather than prose, which is a meaningful behavioral trait. It implies a read-only listing operation, though it does not explicitly mention permissions or error behavior.

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

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

Two sentences, no redundancy, and the most decision-relevant information is front-loaded: what it lists, the size detail, the no-download behavior, and when to call it.

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 listing tool with no output schema, the description adequately explains what the result contains (sections with sizes), what it avoids (downloading prose), and how it fits into a larger workflow. No critical invocation context 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 single parameter design_id is already fully described in the schema with an example, so the description adds little parameter-level meaning. Baseline 3 is appropriate because schema coverage is 100%.

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 specific action ('List the sections of a DESIGN.md'), the resource, and the key output detail (sizes in bytes). It implicitly distinguishes itself from get_design by noting it lists sections without downloading the full prose.

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 states when to use the tool: 'Use this to choose what to read before calling get_design, so you pull one section instead of a 28KB document.' This gives the agent a concrete decision rule and names the related alternative it should precede.

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 discloses partial:true fallback behavior when machine-readable tokens are absent and notes that it explains what is missing. It also signals cost ('cheapest way'). It does not discuss errors or auth, but these are less relevant for a simple read-style token fetch.

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: the first states the core action, the second gives routing guidance, the third explains an important edge case. No filler or redundant restatement of the 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?

The description is sufficient for a simple two-parameter read tool: it states what is returned, which sibling to prefer, and how missing tokens are handled. Without an output schema, it does not describe the exact JSON shape, but the declared token categories and partial:true behavior give an agent enough context to call 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%, so the schema already documents design_id and only. The description lists token categories that mirror the only enum, but adds no new semantic meaning beyond what the schema provides.

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 verb ('Return'), a specific resource ('design system's tokens'), and clarifies the output format ('structured JSON'). It also explicitly distinguishes itself from the sibling tool get_design, saying it should be the default for concrete styling questions.

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

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

The description gives clear when-to-use guidance: it is the cheapest way to answer concrete styling questions and should be preferred over get_design. It does not enumerate all sibling alternatives or specify when to avoid it, so it stops short of a 5.

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

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

With no annotations, the description carries the behavioral burden and meets it: it labels the call as a 'cheap local read' and discloses the exists:false edge case. It could add error behavior or permissions, but for a non-mutating local read the disclosed traits are sufficient.

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 first sentence states purpose and output content; the second gives prioritized usage timing; the third covers the negative case. No sentence is wasted and the most important information is front-loaded.

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

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

The description is complete enough for a one-parameter, read-only tool: it covers what the summary contains, when to use it, and the missing-file return. Because there is no output schema, a slightly more explicit success return shape would make it 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% and the only parameter, project_root, is fully explained in its schema description. The tool description adds no extra parameter semantics, 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 states a specific action (check for and summarize the project's DESIGN.md) and enumerates what the summary covers: originating design system, sections, and colour tokens. The 'current project' and 'local read' framing separates it from the sibling design-search 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?

It gives explicit trigger conditions: before writing/editing frontend code, when resuming UI work, and before fixing visual bugs. It does not name an alternative sibling or state when not to use it, so it falls just short of full routing 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 disclosure burden. It adds a genuinely useful trait beyond the schema: the file is "stamped with its origin so a later session can identify it via get_project_design." However, it does not disclose failure behavior when DESIGN.md already exists and overwrite=false, reversibility, or any permission requirements, which matters for a disk-writing 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?

Two sentences totaling roughly 60 words: the first delivers the action and artifact, the second delivers the decision rule. Every sentence earns its place and the core behavior is front-loaded 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?

The definition is complete enough for a 4-parameter file-writing tool: purpose, output artifact, workflow linkage to get_project_design, and decision context are all present, with parameters fully documented in the schema. It loses a point because there is no output schema and the description does not cover what happens when the target file already exists or what a successful invocation returns.

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 of 3 applies even with no parameter detail in the description. The description adds marginal value by connecting the namespaced design_id example ("getdesign:stripe") to the origin-stamping behavior, but it does not elaborate on any parameter beyond what the schema already documents.

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 multi-step action — "Download a design system and write it to the project as DESIGN.md" — naming both the verb chain and the artifact produced. It also references sibling get_project_design, which distinguishes the install/persist behavior from read-only siblings like get_design, search_designs, and get_design_tokens.

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 second sentence gives an explicit when: "when the project is adopting a design system for real," and a clear when-not: "rather than answering one question about it." It stops short of naming the specific alternative tool for one-off questions, so the exclusion 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?

With no annotations, the description carries the behavioral disclosure burden. It usefully reveals that the tool reports current availability, gating status, and remediation steps such as missing DESIGNMD_API_KEY. This goes beyond a simple 'list' and sets expectations that the output includes actionable status information.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then adds valuable detail about current capabilities and gated features. Every part earns its place.

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

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

For a no-parameter, no-output-schema listing tool, the description is complete: it explains what is shown, the nuance of 'right now', and how to act on gated items. No critical information is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the schema provides no parameter semantics to clarify. The baseline for zero-parameter tools is 4, and the description does not need to add parameter-level 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?

The description uses a specific verb ('Show') with a clear resource ('design catalogs'), and goes further by explaining what it reveals: current capabilities and enablement steps. This distinguishes it from sibling tools that operate on individual designs or searches.

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

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

The description clearly implies when to use this tool: when you need to know which design catalogs are available and their current state. It does not explicitly name alternatives or exclusion conditions, but the context is strong enough for an agent to select it appropriately.

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 for behavioral disclosure. It explains the return type (compact metadata with a namespaced id), the meaning of fetchable:false results (real but gated), and mentions the response's gating map for further detail. It could also cover rate limits or authentication, but for a search operation this is reasonably transparent.

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

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

The description is three sentences long and front-loaded with the core search behavior and examples. It then covers return format, gating semantics, and use case without any filler. Every sentence earns its place, and the structure flows naturally from what it does to how results behave to when to use it.

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 6 parameters and no output schema, the description covers the essential context: scope of search, query types, return format, gating behavior, and the intended use case. It does not fully describe the output structure or pagination, but the gating map mention gives agents enough to navigate results safely. This is complete enough for successful invocation in most workflows.

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 itself does not add much parameter-level detail beyond the schema, but the schema already provides rich guidance, especially for the 'deep' parameter. The tool description's examples ('stripe', 'dark fintech dashboard') reinforce query semantics without replacing schema 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 uses the specific verb 'Search' with a clear resource ('every enabled catalog at once for a design system') and clarifies the query types: brand, style, or mood, with concrete examples. It also notes the output shape (compact metadata with namespaced id), which helps distinguish this from sibling tools like get_design or get_design_sections.

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

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

The description explicitly states when to use this tool: 'when starting new UI work and the project has no DESIGN.md yet.' This is clear context, though it does not explicitly mention alternatives or when NOT to use it, relying on sibling tool names to cover that gap.

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