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

Annotations only declare readOnlyHint=true; the description adds the material behavior beyond that — the operation is a remote API call requiring a key, and there is a documented offline fallback. It does not cover failure modes such as an invalid key or rate limits, so it stops just short of 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 sentences: capability and return contents first, then the auth requirement, then the fallback. No filler, and the result enumeration earns its length because there is no 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, the description carries the return-value burden and does so (findings, severity, remediation, impact, score, type, strengths, top three fixes). Together with the auth prerequisite and fallback, an agent has everything needed to decide whether and how to call it.

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

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

Schema description coverage is 100% and all four parameters (depth, locale, context, description) are documented in the schema itself, including enum meanings and the 20–5000 character range. The description adds nothing about parameters, so this sits at the baseline for schema-covered 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?

States a specific verb and resource ("Audit a described screen or flow") and then enumerates the deliverable: findings mapped to principles and UX smells with severity, remediation, business impact, a score, detected interface type, strengths and three priority fixes. This is precise enough to separate it from list_smells or get_smell 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?

Gives an explicit gating condition ("Pro mode only (UXUI_API_KEY set)") and a named alternative path when that condition fails: use detect_smell then suggest_fix, which run offline. Both the when and the when-not are stated with the sibling tools to use instead.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating operation. The description adds value beyond that by disclosing the return shape (matched smells, confidence levels, suggested fixes), which matters since no output schema exists. It stops short of explaining matching thresholds, maximum result count, or how confidence is derived.

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 compact sentences with zero filler, front-loading what the tool does and following with what it returns. Every clause carries 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 simple two-parameter read-only tool with no output schema, the description covers input purpose and return contents adequately. The only meaningful gap is the unmentioned locale parameter and its effect on results.

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?

At 50% schema coverage, the description reinforces the 'description' parameter's purpose but adds no format or length guidance beyond the schema example. The 'locale' parameter is never mentioned, so an agent cannot tell from the description whether it changes the output language or only the input interpretation.

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 ('Detect potential UX smells') plus the input basis ('based on a description of UI issues'), which cleanly separates it from lookup siblings like get_smell and list_smells. It doesn't explicitly say it is the analysis entry point versus audit_interface, so sibling differentiation is implied rather than stated.

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 phrase 'based on a description of UI issues' implies the trigger condition: free-text complaint input rather than an existing ID. However, there is no explicit when-to-use versus alternatives such as audit_interface or get_smell, and no stated exclusions or prerequisites.

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 only declare readOnlyHint=true, and the description adds the genuinely useful fact that the response contains both structured data and markdown, which compensates for the missing output schema. It still says nothing about failure behavior for an unknown flow_id or about the locale's effect on output, so it isn't fully 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 short sentences, front-loaded with the action and scope, followed by the return shape. Every sentence carries information and there is 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-only, three-parameter generator the description covers the essential purpose and return format. Gaps remain around what the checklist actually contains and what locale changes, which matter since there is no output schema and locale is undocumented in the schema.

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

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

Schema description coverage is 67% — phase and flow_id are already documented in the schema, locale has an enum and default but no description. The description adds only a paraphrase of phase ('pre-flight or post-flight') and gives no meaning for locale, so it does not meaningfully exceed what the schema provides. 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 and resource — 'Generate a ... checklist' — plus the scope ('for a specific flow') and the two variants (pre-flight/post-flight). The resource is clearly distinct from the sibling set (principles, smells, flows), though no sibling is named as an alternative.

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 is called per flow at a specific phase, and the phase enum in the schema clarifies before-design vs before-ship. There is no explicit when-to-use vs when-not guidance and no prerequisites (e.g. whether the flow must already be audited or whether flow_id must exist).

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

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

The readOnlyHint annotation already establishes this as a safe read, so the description only needs to add context. It adds that the response bundles pre-flight and post-flight checklists, which is genuinely useful beyond the annotation, but says nothing about localization behavior, whether the checklists are static or generated, or error handling for unknown IDs.

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, front-loaded with the verb and resource before the usage hint. Nothing is redundant, though the second sentence is thin enough that it barely earns its own sentence rather than being folded into the first.

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 burden of conveying return content and does so only at a high level ('pre-flight and post-flight checklists'). For a two-parameter read tool with one annotation this is close to sufficient, but an agent still cannot tell what a 'flow' object or a checklist entry looks like.

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%: the id parameter is documented exhaustively with twelve enumerated values, while locale has only an enum and default with no prose. The description contributes no parameter meaning at all and does not explain what locale actually localizes, though the self-explanatory enum and default limit the damage.

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 ('Get a user flow') and adds what the payload contains ('pre-flight and post-flight checklists'), which distinguishes it from list_flows by the singular retrieval. It does not explicitly name the neighboring get_flow_principles or list_flows, so the differentiation is implied rather than stated.

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 before designing or shipping a flow' gives a lifecycle moment for invocation, which is more than nothing. However, it never states when NOT to use it, nor names alternatives such as list_flows (for enumeration) or get_flow_principles (for the underlying rules), leaving routing between siblings 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It does add that the result mixes both principles and smells in one response, but says nothing about result shape, size, or what happens for an unknown flow.

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 with no wasted words. It is efficient, if only because it is so short that it omits helpful detail.

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

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

With no output schema, the description should indicate what the response contains and how locale affects it; it does neither. For a two-parameter aggregate tool with an undocumented locale option, this leaves real 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 only 50%, and the uncovered parameter is locale (enum en/es with default en), which the description never mentions or explains. The flow_id enum is enumerated in the schema itself, so the description contributes no meaning beyond structured fields.

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 and resource ('Get the key principles and common smells') and scopes it to 'a specific flow', which separates it from single-item siblings like get_principle and get_smell. It is reasonably clear, though the domain terms 'principles' and 'smells' are not elaborated.

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

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

There is no guidance on when to choose this aggregated per-flow tool over get_principle, list_principles, get_smell, or list_smells. The agent must infer from the name alone that this bundles both categories for one flow.

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 only declare readOnlyHint=true, so the description carries most of the burden, and it discloses a genuinely non-obvious behavior: with UXUI_API_KEY set (pro mode) the full guide body is returned in `content`. That conditional, credential-dependent response shape is exactly the kind of thing an agent needs and cannot infer from the schema. It does not cover failure behavior for unknown slugs.

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 action and lookup key, then the return payload, then the use case. The enumeration of return fields is dense but earns its space because there is no 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, the description does the heavy lifting by naming the returned fields and the pro-mode variation, and the schema covers the two parameters. The remaining gap is edge-case behavior — unknown slug, locale fallback — which an agent calling this tool would reasonably want.

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%, with both `slug` and the `locale` enum documented in the schema itself. The description reinforces the slug-as-lookup-key idea and ties `content` to the API key, but adds no format or validation detail beyond the schema, 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 and resource ('Get a UX/UI principle by its slug') and enumerates exactly what comes back: metadata, summary, citations, and a guide link. The 'by its slug' lookup key implicitly separates it from search_principles and list_principles, which take query/filter inputs rather than a single identifier.

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 this to identify, summarize or cite a specific principle' gives a clear usage context tied to the known-slug case. It stops short of explicitly naming alternatives (e.g., 'if you only have a topic, use search_principles'), so there is no stated when-not-to-use.

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 only supply readOnlyHint=true, so the description carries the behavioral load and does so well: it discloses that results are gated by an API key and that the return shape differs between pro and non-pro modes (prompts field vs. guide URL). It doesn't cover failure modes such as an unknown slug or what the non-pro URL payload looks like.

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, each doing distinct work: purpose, mode-dependent return behavior, and the sibling alternative. No filler and the core action 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?

With no output schema, the description must explain returns, and it does for both auth modes. What's missing is the behavior of the second parameter and any error condition, which matters for a 2-param lookup tool but is a modest 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 coverage is 50%: slug has a description and locale is an enum with a default but no explanation of what it affects. The description never mentions locale or that it controls the language of the returned prompts, so half the parameters remain uninterpreted in both places.

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

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

The description opens with a specific verb and resource ('Get the AI prompts for a specific principle') and explicitly contrasts itself with the sibling get_principle, which returns only the summary. An agent can route between the two without inspecting 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 names the condition that changes the outcome (UXUI_API_KEY set = pro mode returns prompt text; unset = returns the guide URL instead) and gives an explicit alternative ('Call get_principle first if you only need the summary'). Both when-to-use and when-not-to-use are stated.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description's added value is the disclosure of returned content sections (symptoms, fix recipe, related prompts). It says nothing about behavior for unknown IDs, whether missing smells error or return empty, or how locale changes the result.

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 with zero filler; the resource and the returned sections are stated immediately, and nothing is redundant.

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

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

For a simple two-parameter read tool with no output schema, the description adequately conveys what comes back. However, it leaves the locale parameter unexplained and gives no guidance on obtaining a valid ID, which are the remaining gaps an agent would hit.

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 only 50%: 'id' is well documented with examples, but 'locale' has an enum and default with no explanation anywhere. The description reinforces 'by ID' but never mentions the locale parameter or what it localizes, so it does not compensate for the coverage gap.

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

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

The description uses a specific verb plus resource ('Get a UX smell (anti-pattern) by ID') and even names the payload (symptoms, fix recipe, related prompts). The 'by ID' framing implicitly separates it from list_smells and detect_smell, though neither sibling is named 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?

Usage is only implied: 'by ID' suggests the agent must already hold a smell ID (e.g., from list_smells or detect_smell) before calling. There is no explicit when-to-use/when-not statement and no mention of the alternative reading tools in the sibling set.

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

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

The readOnlyHint annotation already establishes this as a safe, non-mutating read, so the bar is lower. The description adds that results include target metrics, which is useful return context, but says nothing about ordering, pagination, or whether "all" is truly 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?

A single front-loaded sentence with no filler; the resource and the returned data are stated immediately. It is arguably too terse given the gaps, but no sentence is wasted.

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

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

For a simple zero-required-parameter listing tool with no output schema, the definition covers the basics but omits sibling differentiation and the meaning of the locale parameter. An agent could call it, but with avoidable guesswork.

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

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

Schema description coverage is 0%, so the description must compensate for the single locale parameter and does not. The enum and default in the schema show the allowed values, but nothing explains what locale actually changes about the returned flows.

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 and resource ("List all available user flows") and adds the payload detail "with their target metrics," which tells an agent what comes back. It does not explicitly distinguish itself from the sibling get_flow, though "list all" versus "get" implies the enumeration/single-record split.

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 call this versus get_flow or the principle/smell listing tools. Usage is only implied by the word "available," leaving the agent to infer that this is the catalog-enumeration call.

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

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

The readOnlyHint annotation already tells the agent this is a safe read, so the description only needs to add context. It does disclose the return shape at a high level ('principle summaries and available parts'), but says nothing about pagination or what the default limit of 20 implies for large result sets.

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, front-loaded with the primary action, with the filtering option and return value packed efficiently. Nothing is wasted, though it is sparse rather than deliberately structured.

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 mention of return contents partially covers the absence of an output schema, which is a plus. However, for a three-parameter tool with low schema coverage, the undefined limit and locale parameters leave an agent under-informed about result volume and language behavior.

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 only 33%: 'part' is documented, but 'limit' and 'locale' are bare. The description mentions the part filter but adds no meaning beyond the schema and says nothing about limit or locale behavior, so it fails to compensate for the coverage gap.

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

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

The description gives a specific verb and resource ('List all UX/UI principles') plus the filtering option, so an agent knows this is an enumeration tool. It does not distinguish itself from close siblings such as search_principles or get_flow_principles, which leaves the boundary ambiguous.

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?

'or filter by part' implies when the filter is useful but states no explicit when-to-use or when-not-to-use rule. With search_principles and get_principle in the sibling list, the agent gets no guidance on why it would list instead of search.

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

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

The readOnlyHint annotation already establishes that this is a safe read, so the description only needs to add context beyond that. It contributes the 'all' scope and the optional-filter behavior, but says nothing about the shape of the returned list, ordering, or pagination, leaving the agent to discover those at call time.

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 with no filler; the scope ('all') and the optional filter are stated before any detail. Nothing could be removed without losing 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 two-parameter read tool with annotations covering safety, the description is adequate but thin. It does not explain how 'locale' affects the returned smell text, whether the list is complete or paginated, or what a smell record contains, which matters given there is no output schema.

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

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

Schema coverage is 50%: 'category' is documented in the schema with example values, while 'locale' relies on its enum and default, both self-explanatory. The description restates the category filter without adding syntax or allowed values beyond what the schema already carries, so 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?

States a specific verb ('List') and resource ('UX smells'), and clarifies the term with '(anti-patterns)', so an agent knows this is a catalog enumeration rather than a lookup. It does not explicitly differentiate itself from siblings like get_smell or detect_smell, leaving the list-vs-single-item distinction to naming convention.

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 filtered by category' implies that filtering is available but not required, which is mild usage guidance. It never states when an agent should call this instead of get_smell or detect_smell, and no exclusions or prerequisites 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?

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read. The description usefully discloses that results include summaries. However, it says nothing about result ordering, whether multiple filters combine with AND or OR, what happens without a query, or pagination behavior beyond the limit parameter.

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, front-loaded with the operation and followed by the return payload. No padding or repetition, though the terseness leaves several behavioral questions unanswered.

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 six-parameter search tool with no output schema, the description covers the basic purpose and the return shape. It leaves out how filters interact, default behavior with no query, ranking of results, and how it differs from list_principles, which are meaningful gaps for a search tool with zero required parameters.

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 83%, so the schema already explains query, part, tags, and limit, including which fields the query searches. The description names four of the six parameters but adds no syntax, matching, or filter-combination semantics beyond what the schema states, and it omits limit and locale entirely. 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?

A clear verb ('Search') plus resource ('UX/UI principles') and the dimensions that can be searched (query, part, difficulty, tags). It also states what comes back ('matching principles with summaries'). It does not differentiate itself from the sibling list_principles, so an agent must infer that this one is the search/filter variant.

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, no exclusions, and no mention of alternatives. With list_principles and get_principle among the sibling tools, an agent has no stated rule for choosing this tool over those. The usage is only implied by the word 'Search' and the filter parameters.

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 adds genuine behavioral context by stating what the tool returns: a detected smell plus a step-by-step fix recipe and refactoring prompt — valuable because no output schema exists.

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 sentences with zero filler; the core purpose is front-loaded and the output description follows immediately.

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, three-parameter tool with no output schema, the description covers what the tool does and roughly what comes back. The only notable omission is the role of the locale parameter and the detection-vs-lookup behavior of smell_id.

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 67%, with 'issue' and 'smell_id' documented in the schema and only 'locale' undocumented. The description adds no parameter-level meaning (e.g., whether omitting smell_id triggers detection, or what locale localizes), so it does not compensate for the gap beyond the 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?

The description names a specific verb+resource ('Get a fix suggestion for a UX issue') and clarifies the payoff (step-by-step recipe plus refactoring prompt). It is reasonably distinct from siblings like list_smells or get_smell, though it never explicitly contrasts itself with detect_smell, which it partly duplicates by also detecting the smell.

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: call this when you have a UX issue and want remediation rather than mere detection. There is no explicit when-not guidance, no mention of when to prefer detect_smell or get_smell first, and no stated prerequisite for supplying an existing smell_id.

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