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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses the return shape ('blockers and the top 5 fixes') and the grading scale/grade mapping, which matters because there is no output schema.

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 dense sentence that front-loads the score/grade outcome and then lists criteria, followed by a short sentence on returns. It is long but every clause adds a distinct criterion, so little 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?

With no output schema, the description does the work of explaining the return ('blockers and the top 5 fixes') and the scale, and it enumerates the scoring dimensions. It is nearly complete for an 8-parameter read-only tool, with only the price/digital/keywords inputs left unexplained.

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

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

Schema description coverage is only 13% across 8 parameters, so the description has to carry meaning. It maps evaluation criteria to several params (title, 13 tags ≤20 chars multi-word, description structure/disclosure, photos and video), but price, digital and keywords are never explained in the description, leaving real gaps.

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

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

The description names a specific verb and resource ('Score a listing 0–100 (grade A–F) against Etsy best practices') and enumerates the exact dimensions being graded, which makes it unmistakably distinct from the generate_*/suggest_* siblings that produce content rather than audit it.

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 by the verb 'score' versus the sibling generators, so an agent can infer this is the audit path. However, there is no explicit when-to-use statement, no mention of when a listing should be scored versus regenerated, and no reference to any sibling by name.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine behavioral context by disclosing the processing outcome: themes are formed by shared terms, one primary phrase is selected per theme, and phrases are flagged tag-ready at the ≤20-character threshold.

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 dense sentence, front-loaded with the core action and followed by outputs and input examples. No filler, and the ≤20 char rule is stated inline where it is needed.

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 shape; it does so at a high level (themes, primary phrase, tag-ready flags). Limits on input size and the exact structure of each theme are not described, which leaves a small gap for a tool with a single structured parameter.

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?

With one parameter and 0% schema description coverage, the description carries the semantic burden and does so reasonably: it specifies that the input should be a raw keyword list and names typical sources. It does not restate the 500-item / 80-character constraints, but it adds meaning beyond the array-of-strings 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 (group/cluster) and resource (raw keyword list) plus the concrete outputs: themes by shared terms, a primary phrase per theme, and tag-ready flags. The framing as an operation over a user-supplied list clearly separates it from the generate_* siblings, which create content from scratch.

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?

Input provenance examples (Etsy autocomplete, eRank, Etsy Stats export) imply the situation in which to use it, but there is no explicit when-to-use vs alternatives guidance and no mention of when to prefer suggest_long_tail or generate_tags 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description goes beyond that by disclosing output structure, a hard 160-character constraint on the opening, and a conditional rule (digital-download disclosure only 'when digital') — genuine behavioral content not in the annotations.

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

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

A single front-loaded sentence ending in a colon-list; dense but every clause names a real output section, and the 'when digital' qualifier is placed at the point of relevance. No filler or restatement of the title.

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 13 parameters, low schema coverage, no output schema, and nested objects, the description is only partially complete: it sketches the returned artifact's sections but not its length limits (e.g. Etsy's 1400-char body cap), and it leaves the more than half of undocumented inputs unexplained. Adequate to call the tool, insufficient to call it well.

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

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

Schema description coverage is only 38% across 13 parameters, including a nested attributes object, so the description must compensate — and it does so only partially. It implicitly maps to keywords, highlights, whats_included, how_to_use, shipping_or_delivery, and digital, but says nothing about modifiers, attributes, dimensions, care_or_requirements, call_to_action, name, or product_type.

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

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

The description opens with a specific verb+resource ('Write a structured, scannable Etsy description') and enumerates the exact sections produced, so the agent knows precisely what artifact comes out. It does not, however, explicitly distinguish itself from siblings like generate_titles or generate_tags, relying on the reader to infer the division of labor.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance at all. An agent selecting among generate_titles, generate_tags, generate_description, and suggest_long_tail gets no routing signal from this text beyond the word 'description'.

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 this as a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuinely new behavioral context: output is capped at 13 tags, each constrained to ≤20 characters, plural duplicates are suppressed, and skipped phrases are reported back to the caller — the last of which is important because it tells the agent that partial results are possible.

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 output constraint, then the input sources and the skipped-phrase reporting. Every clause carries information — there is no filler or restatement of the title.

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 five-parameter generator with a nested attributes object and no output schema, the description covers what is produced (13 tags, character limit, dedup rules) and flags the skipped-phrase report, which is the closest thing to return-value disclosure. It stops short of describing tag ordering or how attributes versus keywords are prioritized when conflicts arise.

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 80%, so the schema already documents keywords ('most important first'), modifiers, product_type, and most attribute fields. The description reinforces which input groups feed the tag set but adds no format, ordering, or interaction detail beyond the schema, so baseline 3 applies.

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

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

The description gives a specific verb (Build) plus the exact resource and dose (up to 13 unique tags) along with hard constraints (≤20 characters, multi-word buyer phrases, no plural duplicates) and the input sources (keywords, attributes, modifiers). That makes the tag-generation role unmistakable, though it never explicitly distinguishes itself from keyword-oriented siblings like cluster_keywords or suggest_long_tail.

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 by the stated inputs ('from keywords, attributes and proven modifiers') and by the 'proven modifiers' qualifier that tells the caller to pass only seller-confirmed descriptors. There is no explicit when-to-use, when-not-to-use, or named alternative among the six siblings, so the agent must infer routing.

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 readOnly, non-destructive, idempotent behavior, so the safety profile is covered. The description adds valuable output constraints (length caps, special-character limits) that go beyond the annotations, but says nothing about determinism or failure modes. Solid but not rich.

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

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

One tight sentence that front-loads the output shape, then lists variant types and formatting constraints. No filler or repetition.

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

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

Describes the output shape and formatting rules, which is the most important context for a generation tool. No output schema exists, so the description must explain return values, and it does so only partially (variant types and character rules, but not ordering or which variant is recommended). Missing sibling routing guidance for a crowded tool family.

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 keywords, modifiers, digital, and several attributes already documented in the schema. The description adds the branding/brand-variant rationale and implies how modifiers are gated, but does not explain the interplay of attributes versus keywords, which is central to output quality. Baseline 3 for a schema that carries most of the load.

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 (build) and resource (Etsy title variants) with the exact output shape (3-4 variants). Names four distinct title strategies, which distinguishes it from siblings like generate_tags and generate_description.

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 by the Etsy-listing context and the output format, but the description never states when to call this versus generate_tags, generate_description, or suggest_long_tail. No explicit alternatives or exclusions are given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context — variant generation via proven Etsy modifiers, a digital/physical branch, and flagging of tag-suitable results — but says nothing about ordering, volume, or output shape.

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 well-formed sentence that front-loads the core action ('Expand a seed phrase') and packs in modifiers, attributes, and the tag-flagging outcome without padding. Efficient and free of waste.

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 suggestion tool with no output schema, the description should hint at what comes back; 'flagging which fit as tags' gives a partial clue but does not describe the result shape or how many variants are produced. Adequate but leaves meaningful gaps for a 5-param tool with a nested object.

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?

Top-level schema description coverage is 0%, with only a few nested attribute fields carrying inline examples. The description compensates partially by signaling the digital/physical choice and the 'attributes' input, but leaves max and extra_modifiers entirely unaddressed, so the gap is only half filled.

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 ('expand a seed phrase into long-tail variants') and names the domain (Etsy modifiers) plus the tagging angle. It's clear what it does, though it doesn't explicitly contrast itself with generate_tags or cluster_keywords, so it falls short of full sibling differentiation.

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 when-to-use or when-not-to-use guidance, and no mention of the sibling alternatives (generate_tags, cluster_keywords) it overlaps with. Usage must be inferred entirely from the purpose sentence.

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