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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: exactly what is computed (needle-change decision, resulting size, recalculated cast-on/stitch/row counts) and that Ravelry may be consulted for the gauge, which is consistent with the openWorldHint.

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, zero filler, and the core purpose (what is compared and what is produced) is front-loaded before the input hint. Every clause earns its place.

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

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

For a 6-parameter, nested-object tool with an output schema and full annotations, the description covers purpose, input modes, and the nature of the results, so an agent can call it correctly. The only gap is explicit routing against similar sibling calculators, which keeps it short of a 5.

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 adds meaning the schema does not: it explains the either/or relationship between pattern_gauge and pattern_id, and frames counts/measurements as the pattern-side inputs to be recalculated. This clarifies the alternative input paths rather than merely restating field docs.

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 verb+resource (compares the user's swatch with the pattern gauge) and enumerates the three concrete outputs: needle advice, projected size, and recalculated pattern numbers. This clearly separates it from siblings like count_stitches or yarn_needed, which do not do gauge reconciliation.

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 input-usage guidance ('Give the pattern gauge, or a pattern_id to read it from Ravelry'), which is useful, but never states when to pick this tool over alternatives such as count_stitches, spread_evenly, or yarn_needed. Usage is implied rather than explicit, with no exclusions.

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, openWorld), and the description adds the important accuracy caveat that weight-only conversion is an estimate. It does not, however, describe behavior on conflicting inputs or how the direction of conversion is chosen.

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, front-loaded with the verb and scope, examples do real work. The closing sentence about yarn being sold by weight is motivational framing rather than operational information, costing it the top score.

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?

An output schema exists so return values need no explanation, but the critical ambiguity for a 5-parameter conversion tool — which combination of grams/yards/meters to supply and what happens if several are given — is left unresolved.

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 schema description coverage at 20%, the description must carry more: it names yarn_id and weight's role but never states that grams/yards/meters are alternative inputs, whether they are mutually exclusive, or how the enum weight values map to ratios. It partially compensates, so a baseline 3.

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 (converts) and resource (yarn amount) with the exact unit spaces involved (grams, meters/yards, skeins), plus concrete example phrasings. It is clearly distinguishable from siblings like yarn_needed or adjust_for_gauge.

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

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

Explicitly says to pass yarn_id when the exact yarn is known and to fall back to a weight-based typical ratio otherwise — a real routing rule between two parameters. It stops short of naming a sibling alternative or a when-not-to-use case, so not 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?

Annotations declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds that the tool flags rows not using every stitch and flags count mismatches, which is real behavioral detail beyond the annotations. Output schema exists so return-format details are rightly left out.

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 what the tool reads, followed by what it flags and when to use it. The inline examples earn their space by showing the input format. Zero 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?

Annotations cover safety, output schema covers returns, and the description covers input format with examples plus flag behavior. Nothing essential is missing for an agent to call this correctly across knitters and crocheters.

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%. The description does not mention the rows, craft, or stitches_before parameters by name, though the row-by-row input model is conveyed implicitly through examples. With a reasonably descriptive schema, 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 (reads/counts), resource (written knitting/crochet instructions row by row), and even gives concrete input examples like '*k2, p2; rep from * to last 2 sts, k2'. It also names the two output behaviors (flags rows missing stitches, mismatched counts), distinguishing it from siblings like spread_evenly or adjust_for_gauge.

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

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

Explicitly states two use contexts: walking someone through a row and checking a pattern for errors. No other sibling is named as an alternative, but the two usage modes are clear enough that an agent knows when to invoke this versus counting manually or using spread_evenly.

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, idempotentHint and openWorldHint, so the safety/idempotency profile is covered structurally. The description adds useful context about the nature of the data (which reference categories exist and how they are cross-regional), but discloses no runtime behavior beyond that.

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 resource scope before the usage hint. The first sentence is a dense list but every clause carries new information; minimal 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?

An output schema exists so return values need no explanation, and annotations cover safety. The description sufficiently covers what data is available and how to query it; the only gap is sibling disambiguation against the conversion/gauge tools.

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%, and the description adds real value by enumerating the topics the `topic` enum encodes and giving concrete `lookup` examples ("4mm", "US 8", "H", "DK", "8 ply", "ssk", "htr") that clarify accepted value formats beyond the schema's terse description.

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

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

States a specific resource (reference tables) with concrete scope: needle/hook sizes, yarn weights across regions, US↔UK term mappings, and abbreviations. This is clearly distinct from the sibling tools, which are pattern/yarn search and calculation/conversion utilities.

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 tells the agent how to use `lookup` (to find one entry) with concrete input examples, which is helpful. However, it gives no guidance on when to prefer this static reference over related siblings like adjust_for_gauge or convert_yarn_amount, nor any exclusions.

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, idempotentHint and openWorldHint, so the safety profile is covered. The description adds behavioral context beyond that: results are ranked by number of projects, and the response places user-substituted yarns next to the pattern's required weight/yardage/gauge and the designer's suggestions. It does not discuss result volume or truncation, which is minor given the 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?

It is a single dense sentence, front-loaded with the 'Yarn substitution:' label, and every clause carries information. It is slightly overloaded in the middle with three parallel pieces of data, but there is no padding 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?

For a read-only lookup with a full output schema and full annotation coverage, the description supplies everything an agent needs: what is returned, how it is ranked, and the comparison context. Return-value formatting is handled by the output schema, so nothing material is missing.

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

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

Schema description coverage is 100%, so all four parameters (pattern_id, limit, same_weight_only, include_discontinued) are already documented in the schema. The description says nothing about any of them, including the important same_weight_only filter, so it adds no semantic value above the structured baseline of 3.

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: it lists yarns other Ravelry users actually used to make a given pattern. The 'yarn substitution' framing and the detail about ranking by project count make the resource concrete. It never names its siblings (search_yarns, match_yarns, get_yarn_details), so an agent must infer the boundary itself, which keeps it below a 5.

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

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

'Yarn substitution' implies the substitution use case, and the mention of the pattern's own weight and gauge suggests a comparison scenario. However, there is no explicit when-to-use versus match_yarns (which sounds like the nearest alternative for gauge-based matching) and no exclusions or prerequisites 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?

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so safety and idempotency are covered. The description still adds real behavioral value by disclosing the result ordering ('nearest first') and the data source (Ravelry's shop directory), which the annotations do not convey.

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 packed sentences: the capability and its data source come first, the mode selection and the concrete 'near me' advice follow. No filler, no 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?

An output schema exists so return values are handled structurally, and annotations cover the safety profile, leaving the description to explain modes and ordering — which it does. Only minor gaps remain, such as the default units and pagination expectations for a 7-parameter 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 a moderate 57% (page, page_size, radius and query are documented in the schema). The description goes beyond that by explaining how latitude, longitude and radius combine into one search mode and by clarifying that 'query' accepts either a shop name or a city — relational semantics the schema alone does not supply. It is silent on 'units', however.

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 ('Find local yarn shops from Ravelry's shop directory') and scopes it precisely, making it immediately distinguishable from yarn/pattern siblings like search_yarns or get_yarn_details.

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 lays out the two operating modes (proximity search via latitude/longitude + radius, or text search by shop name/city) and gives a routing rule for the common 'near me' case. It stops short of stating exclusions or fallbacks, e.g. what to do when coordinates are unknown, so it falls just below the explicit when/when-not tier.

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, idempotentHint and openWorldHint, so the safety profile is covered structurally. The description adds no behavioral context beyond that – no rate limits, auth requirements, or batching caveats (the 20-id cap lives in the schema). The field list describes return content, which the output schema already supplies, so it earns only baseline credit.

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

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

One sentence, front-loaded with the verb and resource before the field enumeration. The long comma list is information-dense rather than padded, though it borders on enumerating what the output schema should carry.

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 an output schema present and rich annotations, the description need not explain return values or safety, and it correctly focuses on purpose and scope. The only real gap is the missing when/when-not guidance relative to search_patterns.

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?

There is a single parameter with 100% schema description coverage, which already documents origin (from search_patterns), type, and the 1–20 range. The description only restates 'by id' and adds no format or edge-case guidance, 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?

States a specific verb (Get), resource (full details for Ravelry patterns), and access path (by id), and the sibling set makes the distinction clear: search_patterns finds ids, this fetches details, and get_yarn_details covers the other resource. The enumerated field list reinforces exactly what 'full details' means. An agent can route here 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 phrase 'by id' implies a post-search lookup, but the description never explicitly says to call this after search_patterns rather than in its place, nor does it flag when not to use it (e.g., for bulk browsing). Usage is inferable but not spelled out.

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, idempotentHint, and openWorldHint, so the safety profile is fully covered externally. The description adds nothing behavioral beyond that (no rate limits, auth needs, or partial-failure behavior), and its field list largely restates what the existing output schema already conveys.

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 preamble; the enumerations of returned attributes are dense but relevant. Slightly long in the tail, but appropriately sized for the tool's scope.

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 annotations covering safety, a 100%-covered single-parameter schema, and an output schema handling return structure, the definition is nearly self-sufficient. The only omission is any guidance on when this is the right lookup versus searching, which keeps it short of a 5.

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

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

Schema description coverage is 100% and the single parameter already documents the 1-to-20 id range and integer type. The description only echoes 'by id', adding no format, ordering, or error-handling semantics 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?

States a specific verb and resource ('Get full details for one or more yarns by id') and the 'by id' qualifier cleanly separates it from sibling search_yarns / find_yarns_for_pattern, which operate by query or pattern. The listed attributes further pin down exactly what 'full details' means.

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 'by id' phrasing implies this is a follow-up to a search (you need an id first), but the description never states when to prefer this over search_yarns or match_yarns, nor any prerequisites. Usage is only implied, not explicit.

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

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

Annotations already cover readOnly/idempotent/openWorld, so the bar is lowered. The description still adds useful behavior: results come with a confidence and alternatives, which tells the agent how to handle uncertain matches. It does not mention batching limits or failure behavior, so not 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 tight sentences: purpose, input shape, then return + follow-up. Front-loaded and every sentence earns its place with no repetition of structured fields.

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?

Output schema exists, so return values need not be explained, yet the description briefly and usefully characterizes them (best match, confidence, alternatives). Input, output, and next-step context are all present; only edge behavior (limits, no-match handling) is absent.

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 reported as 0%, so the description must carry the load, and it does: it enumerates the readable fields to supply per item (brand, name, weight, fiber, yards/meters, grams per skein) and clarifies the one-item-per-yarn structure. It omits the enum values for weight and the item cap, which the schema already supplies.

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: 'Finds the Ravelry yarn behind text read from a ball band, receipt or invoice.' The input-source framing implicitly differentiates it from search_yarns (query-based lookup), though it never names that sibling. Clear purpose, but not explicit sibling routing.

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 concrete invocation context ('Pass one item per yarn with the raw label plus whatever you could read') and routes the agent downstream ('use the yarn ids with add_to_my_stash or get_yarn_details'). No when-not guidance or ambiguity handling instructions, but the positive guidance is strong.

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/openWorld/idempotent, so the safety profile is covered. The description adds genuine workflow context by describing the paginated result shape and the two-step search-then-detail pattern, though it says nothing about rate limits or result caps beyond the schema's page_size.

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 core action and ending with the actionable next step. The filter enumeration is dense but earns its place by previewing the filter surface.

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?

An output schema exists, so return values need not be re-explained, and the description covers scope plus the follow-up call. For a 16-parameter tool the description is adequate, though it could note pagination behavior more explicitly.

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 every parameter is documented in-schema with enums and defaults, so the schema carries the semantics. The description's filter list largely restates those schema fields without adding syntax or format detail, matching the baseline 3.

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 (search) and resource (Ravelry pattern database), then enumerates the filter dimensions. It is clearly distinct from sibling search_yarns, which covers a different resource.

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?

Tells the agent it returns a page of matches and explicitly routes follow-up work to get_pattern_details for yarn, gauge, needles and notes. It gives no when-not guidance or comparison to sibling searches, 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?

Annotations already establish read-only, idempotent, open-world behavior, and the description usefully adds the non-obvious default that discontinued yarns are excluded and a summary of what each match contains (yardage/grams, washability, rating). It does not discuss pagination limits or result caps, which remain undocumented in prose.

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 carrying distinct information: what is searched, the default exclusion rule, and the return payload. The scope of search is front-loaded with no filler.

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

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

For a read-only search with full annotation coverage, a complete output schema and fully documented parameters, the description supplies the two things structured fields do not: search dimensions and the discontinued-exclusion default. Pagination behavior is left to the schema, which is acceptable but leaves a minor 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 description coverage is 100%, so each parameter is already documented with enums, defaults and examples such as the "Malabrigo Rios" query example. The description restates the filter categories (name, weight, fiber, attributes) at a high level without adding syntax or constraint detail beyond the schema, making the baseline 3 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 (Search) and resource (Ravelry yarn database) and enumerates the filter dimensions, so the agent knows exactly what the tool returns and how it can be narrowed. It does not explicitly distinguish itself from close siblings such as find_yarns_for_pattern or match_yarns, which requires the agent to infer the difference.

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?

"Excludes discontinued yarns unless asked" gives a clear default behavior, but there is no explicit when-to-use guidance or routing between this and alternative yarn tools. Usage is implied (search by name/fiber/weight/attributes) rather than stated against 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?

Annotations already establish that this is a read-only, idempotent, closed-world computation, so the bar is lower. The description adds genuine value beyond them by disclosing the craft-specific technique mapping (M1/k2tog for knitting, 2 sts in one/sc2tog for crochet) and that the result is a ready-to-use written instruction.

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, front-loaded with the core action and immediately backed by a concrete example, with no filler. Every clause carries 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?

An output schema exists, so the return value need not be explained (though the description still helpfully notes it returns the written instruction). Coverage is solid for a 5-parameter computation tool, with the only real omission being any explanation of the flat-vs-round 'worked' option.

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 60%, with 'change', 'stitches', and 'stitch' already documented in the schema. The description reinforces the increase/decrease and knitting-vs-crochet semantics but says nothing about the 'worked' parameter (flat vs. round) or the enum meanings, so it does not fully compensate for the coverage gap. Baseline 3 fits.

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 (spaces increases/decreases evenly) with the exact resource (stitches across a row or round) and names the concrete output (the written instruction). The worked example "increase 13 stitches evenly across 97" makes the function unmistakable and clearly distinct from count_stitches or adjust_for_gauge.

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 example implies when the tool applies, and the mention of both knitting and crochet techniques hints at scope, but there is no explicit when-to-use vs. when-not-to-use guidance and no named alternative among siblings such as adjust_for_gauge. Usage must be inferred.

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, openWorld, so safety is covered. The description adds useful context about data sourcing (Ravelry pattern/yarn vs direct numbers) and the safety-margin concept, but says nothing about edge cases or what happens when both direct numbers and IDs are supplied.

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 packed sentences with no filler, and the core computation is front-loaded before the data-source and scale caveats.

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?

An output schema exists, so return values need not be explained. For a 7-parameter, all-optional calculator the description covers the dual input paths and scaling adequately; only the skein-length parameters and mutual exclusivity of inputs are left implicit.

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 57%, so the schema carries roughly half the load. The description clarifies the scale and pattern_yards intent, but largely restates the schema's own wording on scale, and never explains yards_per_skein vs meters_per_skein or the yarn_id/pattern_id pairing, leaving part of the gap unfilled.

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: computing how many skeins to buy for a pattern with a given yarn, including a safety margin. The scope (skein count for purchasing) is distinct from siblings like convert_yarn_amount and adjust_for_gauge, though it never names an alternative to sharpen the boundary.

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 implies two input modes (pull yardage from a Ravelry pattern/yarn, or supply numbers directly) and mentions optional scale handling, which hints at when the tool applies. It gives no explicit when-not guidance and never routes the agent away from the closely related adjust_for_gauge or convert_yarn_amount siblings.

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