The Spool List

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: buyer identities and full briefs are withheld, and detail/quoting requires a free maker sign-up. It stops short of disclosing result volume, ordering, or pagination behavior.

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

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

Two sentences, both front-loaded and dense: the first states scope and enumerates the projection, the second states the data limitations and gating. No filler or repetition 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 two-optional-parameter read-only browse tool with no output schema, the description usefully substitutes for a return spec by listing the visible fields and explicitly stating what is hidden. The main remaining gap is any indication of result set size, ordering, or whether results are paginated.

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 both parameters are documented inline with examples (ISO code "US", keyword "helmet"), so the schema carries the load. The description does not explain the filters at all; its use of "country" refers to a returned field rather than the filter, which adds no semantic depth for the parameters.

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 ("List current open jobs") and goes further by enumerating the returned fields (title, country, budget, posting time). It does not explicitly contrast itself with any sibling, but the resource is unambiguous enough that an agent can distinguish it from search_makers or estimate_job_cost.

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 context is only implied: the mention that "buyers have posted" and "makers can quote" suggests the maker-sourcing use case, and the sign-up note hints at the pre-registration browsing path. There is no explicit when-to-use vs. when-not guidance and no sibling is named as an alternative, so the agent must infer the route.

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=true and destructiveHint=false, and the description reinforces this with an emphatic 'Nothing is posted' — valuable because the 'create_' name would otherwise imply a write. It also discloses the downstream flow (user reviews, adds photos, posts, free for buyers), though it says nothing about link lifetime or reuse, which the idempotentHint implies but never explains.

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

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

Two sentences, no filler. The core action is front-loaded and the no-posting constraint plus the user's follow-up steps follow immediately in the same compact span.

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 usefully implies the return value is a link the user opens. For a five-parameter, non-mutating tool that is largely sufficient, though it could say what a caller should do with the returned link and whether re-calling produces the same link.

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 category, deadline, budget and description. The description adds no field-level guidance, not even which fields are required or how free-text description maps to the brief; it only restates that the input is a description of the wanted item.

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: turning a user's description into a pre-filled job post link on The Spool List. Crucially it clarifies that nothing is posted, which distinguishes it from any sibling that might create or browse actual jobs.

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 usage context is clear — the user wants something custom-made and will review and post the brief themselves. However, no sibling is named and no exclusion or alternative (e.g. estimate_job_cost for pricing-only questions, browse_open_jobs for existing listings) is stated, leaving routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: results are an indicative range rather than a binding quote, prices originate from rate cards, and makers set their own prices — a caveat the agent should relay. Precision, currency and rounding behavior are not stated, keeping it below the top mark.

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 the core purpose front-loaded and the caveat second. Nothing is redundant, and 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?

With five fully documented parameters, rich annotations and no output schema, the burden on the description is light. It covers what the tool does, what feeds the estimate, and the key interpretive caveat about the output being non-binding; currency is already specified in the schema.

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

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

Schema coverage is 100% and defaults/enums are already documented, so the baseline is 3. The description still adds value by explaining how inputs combine into the estimate — hourly rate scaled by discipline and complexity, plus materials, setup and quantity — which tells an agent which parameters actually move the result.

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 ('Ballpark price range for a fabrication job') and even discloses the rate source ('The Spool List rate cards'), listing the factors it accounts for: hourly rate by discipline, complexity, materials, setup and quantity. No sibling tool does cost estimation, so an agent can route here unambiguously.

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

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

Usage is only implied — an agent can infer this is for pre-quote budgeting rather than actual booking. There is no explicit 'use when' statement, no exclusions, and no reference to siblings like browse_open_jobs or find_local_services for agents seeking real quotes or maker contact.

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 and openWorld=false, so the description needn't re-explain safety. It adds real value by disclosing the returned fields and, importantly, that contact details are withheld and live on the listing page — a limitation an agent could not predict from the schema or annotations alone.

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 purpose and scope, then return shape. The category example list is the only slightly padded element, though it usefully signals breadth. 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 no output schema, the description steps in and names the return fields (business name, category, area, listing link) plus the contact-detail limitation, which is the right call. Minor gap: it says nothing about result ordering or what an empty city match means, despite a limit parameter with a 20 cap.

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% with examples for city, country and limit, so the schema carries parameter meaning. The description adds only the 'in or near' nuance for city and a partial sampling of the category enum; it does not explain how the 35 enum values map to user intent or what happens with unmatched categories.

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 ('Find') and resource ('local service businesses listed on The Spool List') with a clear geographic scope ('in or near a city'). The category examples sharpen what counts as a 'service business', though no sibling tool is named or explicitly excluded, so an agent must infer the boundary with search_makers on its own.

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 rather than stated: the agent can infer this is the tool for locating businesses by city, but there is no explicit when-to-use or when-not-to-use guidance, no prerequisites, and no pointer to any alternative. Acceptable, not instructive.

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, and closed-world, so the safety profile is fully covered. The description adds value beyond that by specifying 'public profile' (only public data is exposed) and by enumerating the fields returned, which matters because there is no output schema. It does not state what happens when the handle is unknown, a minor remaining gap.

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 the verb and lookup key first, followed by the returned fields. Every clause earns its place and there is no filler.

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

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

With one required parameter, full schema coverage, and no output schema, the description carries the burden of describing the return value — which it does by listing the profile fields. The only missing piece is error behavior for a nonexistent handle, which is minor for a simple read 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%, and the handle parameter already documents the optional '@' prefix and gives an example. The description only restates 'by handle', adding no new syntax or constraint information, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a maker's public profile') and scopes it 'by handle', which implicitly separates it from the sibling search_makers. It enumerates the returned content (display name, tier, badges, stats, job availability, shop links), so an agent knows exactly what data comes back. It stops short of naming a sibling explicitly, keeping it at 4 rather than 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?

The 'by handle' phrasing implies the usage condition: you already know a specific maker's handle and want their details rather than a search. No explicit when-to-use, when-not, or alternative (e.g. search_makers for discovery) is stated, so guidance is only implied.

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 read-only, idempotent, closed-world, and non-destructive behavior, so the safety profile is settled. The description usefully signals that each list carries different payloads (disciplines include base hourly rates, markets include item counts), which hints at return contents despite there being no output schema. It does not say whether values are IDs, slugs, or display names, nor whether the three lists come back in one payload.

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 with no filler; the framing ("Reference lists for the other tools") is front-loaded before the three-item breakdown. It is slightly list-heavy but every clause carries information about a distinct returned dataset.

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 and no parameters, the description must carry the burden of describing return values; it partially does by enumerating the three lists and some of their fields. It leaves out the response shape (one object with three keys vs. separate lists) and identifier format, which an agent needs to chain the results into create_job_request_link or estimate_job_cost.

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 no parameters, so the baseline is 4 and nothing in the description conflicts with that. It correctly avoids inventing input semantics for a zero-argument tool.

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 the resource (reference lists for job categories, estimate disciplines with base hourly rates, and shop markets with item counts) and identifies which sibling tools consume each list, which distinguishes it from the search_* and create_* tools. It never states the verb explicitly ("returns"/"lists"), relying on "Reference lists" to imply enumeration.

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?

By naming create_job_request_link and estimate_job_cost as consumers, it implies this tool should be consulted before those calls, giving implicit sequencing guidance. It does not state when not to call it, whether the data is cached/static, or that it should be called before choose-an-id parameters.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to spend its words on the return shape, which it does: title, designer, licence, price and a link to the design page. That return-field disclosure is genuinely valuable because there is no output schema. It does not mention result ordering or how limit truncation behaves, keeping it below 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?

Two sentences, front-loaded with what is searched and immediately followed by what comes back. Every clause carries information, including the note that the linked page is where members download or commission a make.

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 correctly carries the burden of describing returned fields, and all three parameters are documented in the schema. What is missing is routing guidance against the other search_* siblings, but for a simple three-parameter read tool this is otherwise sufficient to call it correctly.

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

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

Schema description coverage is 100%, including examples for query and the default/max for limit, so the baseline is 3. The parenthetical 'price (if any)' loosely gestures at the free_only filter but never states that relationship, so the description adds no meaning beyond the schema.

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

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

Names a specific verb (Search) and a specific resource (The Spool List design library of 3D-printable and fabrication designs), so an agent can tell it apart from siblings like search_makers or search_shop_items by the object being searched. It stops short of explicitly contrasting itself with those siblings, so it lands at 4 rather than 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?

The intent to find a design is implied by the description and the query examples, but there is no statement of when to prefer this over search_shop_items or search_makers, and no exclusions or prerequisites. Usage must be inferred from the resource name alone.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value beyond that by detailing exactly what is returned (name, handle, city/country the maker chose to show, jobs completed, materials, profile link), which tells the agent this is a limited public-fields read rather than a full profile dump. It doesn't mention pagination or result ordering, keeping it from 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?

Two sentences: the first front-loads the discovery action and searchable facets, the second packs the optional narrowing and the exact return payload. No filler and nothing repeated from the schema verbatim.

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 4-parameter read tool with full schema coverage and clear annotations, the description supplies the action, the facets, the optional filters, and the return shape – enough to invoke it correctly. Minor gaps (ordering, empty-result behavior) are tolerable given the annotations and absence of an output schema.

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

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

Schema description coverage is 100%, and the schema itself provides examples for query, country (ISO codes), city, and limit. The description reinforces the query's facets and the optional geographic filters but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 (Find) and resource (independent makers on The Spool List), and enumerates the searchable dimensions (skill, material, name, shop) plus the optional geographic narrowing. The scope is clearly distinguishable from siblings like search_shop_items or get_maker_profile, which operate on items or a single maker rather than maker discovery.

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

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

The description gives clear context for when to use it: discovering makers by skill/material/name/shop, with optional country or city narrowing. It doesn't explicitly name an alternative tool or exclusion (e.g., 'use get_maker_profile once you have a handle'), so it falls short of a 5, but the usage context 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuine value by listing the fields returned (title, price, maker, item link), which matters because there is no output schema; it does not cover result ordering or empty-result behavior.

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

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

Two sentences, zero filler: the first defines scope and the second defines the return shape. Information is front-loaded and every clause carries meaning.

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

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

For a two-parameter read-only search with full schema coverage and no output schema, the description covers purpose and return fields sufficiently to invoke it correctly. Minor gaps (ordering, empty results) are low-risk for this tool class.

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 both the query and limit parameters are already fully documented in the schema, including the default of 10 and the 20-item cap. The description adds no syntax, matching, or ranking details beyond what the schema provides, 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?

States a specific verb and resource ('Search ready-made items makers sell in The Spool List shop (the Forge)') and enumerates the item types covered, which tells an agent exactly what corpus is searched. It does not explicitly distinguish itself from sibling tools like search_design_library or search_makers, so the agent must infer the boundary from the shop/Forge framing.

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 domain wording — searching the shop catalog for physical goods like prints and miniatures — but there is no explicit when-to-use, when-not-to-use, or named alternative. The agent gets context, not routing guidance.

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