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

No annotations are supplied, so the description carries the full burden. It adds real domain context (optionalDependencies, version "instance", the --fa deploy path), but leaves the most consequential behavioral question open: does it only report findings or also mutate package.json? Read-only is inferable from 'analyzes' but never stated, and there is no mention of return shape or failure modes.

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

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

Two sentences, front-loaded with the what before the when, with no filler. The trailing 'regardless of the local preview workflow' clause is slightly awkward but does eliminate a real mis-selection, so it 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 no annotations, so the description must cover the whole picture. It handles purpose and triggering well, but an agent still cannot tell whether the tool writes to package.json or only recommends changes, nor what the analysis produces. Adequate but with a meaningful gap for a mutation-adjacent tool.

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

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

Schema description coverage is 100%, so both packageJsonPath and plannedComponentTags are already documented in the schema; the baseline is 3. The description reinforces the domain meaning of the components involved but adds no syntax, format, or default guidance 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 verb (analyzes) and a precisely bounded resource (a Next Experience UI component project's package.json) plus the exact thing being looked for: platform components that should be declared as optionalDependencies with version "instance". An agent can tell this apart from validate_now_ui_manifest or resolve_component_package 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?

Gives an explicit trigger: 'Use this when adding or changing instance-backed platform dependencies', and ties it to a concrete downstream action (preparation for snc ui-component deploy --fa). It also clears away a potential false trigger with 'regardless of the local preview workflow'. No sibling alternative is named, 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 full disclosure burden. It reveals process expectations (require a separate .scss file plus a styles property; declare instance-backed components in package.json under optionalDependencies), but says nothing about whether the tool is read-only, what it returns, or how errors surface. These are policy rules for downstream code rather than the tool's own behavior, leaving real gaps.

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

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

The purpose is front-loaded, but the description spends several sentences on downstream coding conventions (the .scss/styles property requirement and package.json optionalDependencies declaration) that govern follow-up work rather than how to invoke this evaluation tool. Every sentence is coherent but not all of them earn their place against the tool's job.

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 no annotations, so the description should describe what the evaluation produces (the verdict shape: use-directly vs wrap vs custom). It never does, instead prescribing how to implement a custom component after the fact. For a decision/evaluation tool this is a meaningful omission, though usage context is otherwise 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 100% and all three parameters (useCase, desiredEvents, desiredProperties) are well documented in the schema itself. The description adds no extra parameter detail, so the 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?

The description states a specific decision verb and resource: it evaluates whether an HDS platform component should be used directly, wrapped, or replaced. This is a clear, distinguishable purpose within the sibling set (search/recommend_instance_components), though it never explicitly names the sibling tools it is meant to precede or replace.

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 timing cues: “use this before scaffolding new UI from scratch and before inventing custom wrappers,” and states a strong default (“MUST prefer existing platform components such as now-card”). It lacks named alternatives or when-not-to-use conditions, 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?

No annotations are provided, so the description carries the full burden. It implies a read-only informational tool but does not state side effects, permissions, or that it returns static explanatory text. Adequate but not rich behavioral 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?

Two tightly written sentences with purpose front-loaded. Every sentence earns its place: the first defines the tool's scope, the second gives a usage trigger.

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

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

For a zero-parameter tool with no output schema, the description covers what it explains, the underlying rule, and when to consult it. It could mention that the output is a static explanation, but otherwise it is complete enough.

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 appropriately adds no parameter detail because none exist.

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 ('Explains') and resource ('now-ui.json'), plus the rule it covers. It is clearly explanatory rather than a validation tool like validate_now_ui_manifest, but does not explicitly name or contrast with any sibling.

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 a clear trigger: 'Read this before creating or editing a component if you are unsure whether the manifest needs updating too.' Gives context for use but no explicit exclusions or named alternatives.

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 exist, so the description carries the full burden and does so: it names the backing tables (sys_ux_lib_component, root_component, root_component_definition), warns results may be newer/richer than public npm, and states the environment/auth prerequisite (NEXT_UI_INSTANCE_URL plus credentials). It also enumerates what comes back (props, dispatched_events, availableSlots).

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?

It is longer than typical, but front-loaded with purpose and each sentence contributes (source tables, npm caveat, pre-call guidance, prerequisite). The dense em-dash clause is slightly heavy but no sentence is disposable.

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 must convey return content — it does by listing props, dispatched events, and slots and their source. Combined with the auth prerequisite and the alternative-tool routing, an agent has everything needed to invoke 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?

Schema coverage is 100% and the single parameter is fully documented in the schema with an example value. The description adds marginal context by explaining the tag is resolved against sys_ux_lib_component, but the schema already does the substantive work, so the baseline of 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?

Specific verb+resource: looks up the live API (props, slots, dispatched events) of a Now/Next Experience UI component, with concrete tag examples. It distinguishes itself from siblings search_instance_components and resolve_component_package by emphasizing the instance-resident source of truth rather than published package metadata.

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?

Explicit when-to-use ('Call this BEFORE writing custom markup/logic that duplicates something a platform component already provides') and a named alternative with a clear selection condition ('Use search_instance_components first if you do not already know the exact tag'). Both the positive trigger and the pre-requisite routing 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?

With no annotations, the description carries the full burden and does reasonably well: it enumerates the returned artefacts (now-ui.json stub, .storybook/main.mjs, a story, an .scss stylesheet wired via createCustomElement), the mandatory runtime shim imports, and the instance-backed optionalDependencies convention. It stops short of stating whether anything is written to disk, what the response envelope looks like, or prerequisites/failure modes, but the output content 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?

The purpose is front-loaded in the first sentence, which is good, but the remainder is an unstructured run-on block of MUST clauses that mixes scaffold-output constraints with general agent policy (prefer now-card, use className, don't hand-write createElement trees). Much of that content is relevant yet verbose and would be tighter as explicit bullets.

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

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

Given no annotations and no output schema, the description is the only source of return-value information and covers the scaffold's constituent files and hard import constraints thoroughly. It is complete enough for an agent to call and use the result, with only the mechanical details of the response shape left unspecified.

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% at three parameters, so the schema already documents scopeName, componentName and elementPrefix with defaults and formatting rules. The description adds no parameter-level detail beyond what the schema states, 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 opening sentence states a specific verb and resource: it returns a minimal Now/Next Experience UI Framework component scaffold built on Storybook with a named addon. An agent can distinguish this from sibling tools like get_framework_guidance or validate_now_ui_manifest, though the description never explicitly names or contrasts 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?

There is conditional guidance about preferring the JSX scaffold for new components without an existing repo style, and about preserving existing project configuration, but these are behavioural rules for the generated output rather than explicit when-to-call-this-tool-vs-alternatives instructions. Nothing tells the agent when to reach for get_component_scaffold instead of get_framework_guidance or recommend_instance_components.

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 meaningfully disclose return content and default behavior ('When called without arguments, it defaults to create-custom-element guidance'), which is exactly the kind of behavior an agent needs. It never states that the tool is a non-mutating read of bundled guidance, but for a knowledge-retrieval tool this is minor.

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 purpose is front-loaded in the first sentence, but the body is a long wall of prescriptive framework rules (className vs class, optionalDependencies 'instance' versioning, shim import paths) that largely restate what the tool returns rather than describing the tool. Several sentences could be folded into the returned content without loss to tool selection.

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 must explain what comes back, and it does so explicitly by enumerating the bundled topics and the no-arg default. Combined with the two optional selector params documented at 100% coverage, an agent has enough to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it explains the default when both optional params are omitted, and frames both params as retrieval selectors (direct topic vs. closest bundled topic). That default behavior is not derivable from the schema alone.

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 establishes a specific purpose: retrieving MANDATORY workflow guidance for ServiceNow Now/Next Experience UI Framework projects, and enumerates the bundled content (scaffold pattern, workflow contract, manifest rules, decision flow). It implicitly separates itself from siblings by naming get_component_scaffold as the source of the actual JSX scaffold, but it never explicitly contrasts itself with guidance-adjacent siblings like explain_now_ui_manifest or get_component_api.

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 is emphatic about compliance ('MUST use', 'MUST prefer', 'MUST NOT hand-write') and discloses the no-argument default of create-custom-element guidance, which tells the agent how the call behaves. However, it never says when to invoke this tool versus get_component_api, explain_now_ui_manifest, or evaluate_platform_component_fit; the usage context is only implied by the domain framing.

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 usefully explains that props/events are enriched from live instance metadata when available, which tells the agent results may vary by instance. It does not cover auth needs, what happens when metadata is unavailable, or how recommendations are ranked.

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 no filler; the capability statement is front-loaded and the usage directive follows. Nothing is redundant, though it stops just short of the density a top score would require.

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 read-only, zero-required-param recommendation tool with full schema coverage and no output schema, the description covers purpose, data source, and usage trigger adequately. The main gap is that result shape and fallback behavior when live metadata is missing are left unstated, but no output schema means return values need not be explained.

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 limit, useCase, desiredEvents, and desiredProperties with examples and a default. The description adds no parameter-level syntax or format beyond restating that props and events come from instance metadata, 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 (recommends) and resource (HDS platform components) and names its data sources: a curated registry plus live ServiceNow instance metadata for props and dispatched events. It is clearly distinct from the search/validate siblings, though it never explicitly names them.

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 clear when-to-use guidance: 'Use this before inventing a custom component when an existing platform component may already fit.' No explicit when-not or named alternative (e.g. evaluate_platform_component_fit), but the trigger condition 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, the description carries the transparency burden and does well: it explicitly states the tool 'Never guesses from the tag name' and returns an 'unknown' result rather than inventing a package. That failure-mode disclosure is exactly what an agent needs; it only lacks detail on the exact shape of the unknown return.

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 purpose, followed by an illustrative example and the failure contract. No filler, though the example sentence is close to restating the schema's own example values.

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 lookup with no output schema, the description covers purpose, the sub-component resolution rule, and the unknown fallback. It stops just short of describing the exact returned value in the unknown case, which is the only meaningful 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?

Schema coverage is 100%, so the baseline is 3. The description adds real semantics beyond the schema: the example pair now-card / now-card-header -> @servicenow/now-card shows that sub-component tags collapse to a base package, which is non-obvious from the parameter definition alone.

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 precise verb and resource: 'Returns the exact npm package that a ServiceNow HDS component tag belongs to.' The tag-to-package mapping is distinct from sibling tools like get_component_api or get_component_scaffold, so an agent can tell what this does without opening the 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 makes the triggering scenario clear (you have a component tag and need its npm package) and illustrates it with concrete inputs. It does not name an alternative tool or state when NOT to use this one, but the context is unambiguous for a single-purpose lookup.

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 that results come from a curated registry and are enriched with live instance metadata only 'when available' (i.e., graceful degradation), but it says nothing about ranking, permissions, rate limits, or what happens when no instance connection 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 tightly written sentences with the core behavior front-loaded and no filler. The only mild redundancy is the adjective 'curated', which does not change how the agent invokes 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?

No output schema exists, and the description partly compensates by indicating what comes back (registry matches enriched with live instance metadata). All parameters are optional and documented, so an agent has enough to call it; only result ordering/emptiness behavior is unstated.

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 every parameter (query, actionName, propertyName, limit) is already documented in the schema, and the description adds no syntax, matching behavior, or combination semantics beyond that. 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?

The description gives a specific verb ('Searches') and a well-defined resource ('curated HDS component registry'), plus a secondary behavior (enriching matches with live ServiceNow instance metadata). It does not explicitly differentiate itself from close siblings like recommend_instance_components or evaluate_platform_component_fit, but the 'search/lookup' framing is clear.

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 states a concrete when-to-use condition: 'when an agent needs to discover likely platform components before choosing a dependency or writing custom UI code.' That is a clear context, but no when-not guidance and no alternative tools (e.g., the recommender or fit-evaluator siblings) are named, so it stops 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?

With no annotations, the description carries the full burden and mostly does: it discloses the auth/configuration requirement (NEXT_UI_INSTANCE_URL and credentials) and that results are drawn from the instance's real now-icon package. Read-only semantics and any rate/limit behavior are left implicit.

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 purpose, then usage guidance and result-format details. The sentence about reading from the now-icon package is somewhat redundant with the opening claim but still reinforces authenticity; otherwise 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 must explain return shape, and it does: base names in dash-case with suffix conventions. Combined with disclosed auth prerequisites and validation behavior, an agent has enough to call it correctly, though no pagination/limit guidance is offered beyond 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 coverage is 100%, so baseline is 3, but the description goes further by explaining what `query` values match and how the returned base names map back to an `icon` property via -outline/-fill suffixes. It adds retrieval semantics rather than merely restating parameter types.

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 (searches) and resource (the icon library on the configured ServiceNow instance), and scopes it to the `icon` property of named HDS components. An agent can distinguish it from search_instance_components, which deals with components rather than icons.

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 BEFORE picking an icon name instead of guessing" gives explicit timing guidance, and the note that passing a full name also validates the base icon adds a clear secondary use case. No when-not condition or named alternative sibling is offered, 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 burden and does reasonably well: it discloses the validation rules applied (schema package + tileIcon non-empty check), that it accepts either an object or a JSON string, and what the result conveys. It does not state that the operation is side-effect-free, whether it requires instance connectivity, or how validation errors are structured, so it falls short of full 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 tight sentences: what it validates, what it accepts, what it returns. Zero filler and the core purpose is front-loaded in the first clause.

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 validation tool with no output schema, the description covers the essential gaps by summarizing the return value (validity plus schema/tileIcon issues). It omits error-shape or failure-mode detail, which is minor given the tool's simplicity.

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

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

Schema coverage is 100% for the single 'manifest' parameter and the schema already documents the anyOf object/string acceptance. The description restates that dual input format, adding only marginal value beyond the structured field, 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 (validates) and resource (now-ui.json manifest), and names the exact mechanism (ServiceNow component-schema-validation package) plus a second check (non-empty tileIcon on uiBuilder objects). This is clearly distinguishable from the sibling explain_now_ui_manifest, which explains rather than validates.

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 — you call this when you have a manifest that needs checking before use — but the description never states when to prefer it over explain_now_ui_manifest or what to do with the result. No prerequisites, no when-not conditions, no explicit alternative routing.

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