firestarter_catalog_search

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

Annotations declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description reinforces this with 'Read-only: never charges or changes anything' and adds substantial context beyond the annotations: the meaning of the buyable flag, result ordering ('buyable, cheapest first'), environment behavior ('test/live follows the API key's environment'), and pagination behavior ('when more exist the result notes it'). This fully informs an agent about side effects, result semantics, and edge cases.

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 description is long but densely packed — every sentence contributes distinct information: purpose, differentiation, result contents, buyable semantics, ordering, country filtering, environment, limits, and read-only safety. It is well-organized and front-loaded, but the length is at the upper edge for a tool description, so it doesn't achieve perfect conciseness.

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 the tool's complexity (7 optional parameters, result semantics, environment behavior, and a sibling with overlapping scope), the description is fully complete. It tells agents what results contain, how to interpret buyable vs browse-only, how ordering works, what to do when more results exist, and that the operation is side-effect-free. An agent can invoke this tool correctly without any additional external knowledge.

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 all 7 parameters. The description goes further by giving practical search-quality advice for query ('matches best on real product nouns'), explaining what does NOT belong in query ('price constraints belong in max_price'), and revealing hidden behavior ('price phrases that do slip into the query are auto-extracted into the price filters'). This adds real value beyond the schema, though a bit more per-parameter detail could push it to 5.

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

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

The description opens with a specific verb and resource: 'Search the Firestarter NETWORK catalog — products listed for sale by ALL sellers — without starting a purchase.' It also names the buyer-facing role and distinguishes itself from firestarter_listings, making the tool's scope immediately unambiguous.

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 explicitly states when to use this tool ('buyer-facing browse tool,' 'see what's available before buying, compare prices, or check whether the network carries an item') and directly names the alternative it is not: 'Different from firestarter_listings, which only shows YOUR OWN seller listings.' It also tells agents how to chain the resulting listing_id into firestarter_execute, providing clear workflow guidance.

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