Storefinch

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so the safety bar is low. The description nonetheless adds behavior the annotations cannot express: the returned link expires in 24 h, each exported row consumes the plan's monthly quota, and a preview shows the first rows before committing.

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: output shape first, prerequisites second, cost/expiry third. The column enumeration earns its space because there is no output schema. 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 an export tool with no output schema, it covers the important unknowns: returned columns, link lifetime, quota consumption, and preview behavior. Missing only details like the truncated-vs-complete preview boundary and how max_rows interacts with quota.

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?

Coverage is 64%, and the description only adds the high-level 'category + location' requirement, which the schema already enforces via required. It says nothing about require_phone/require_website defaults, min_confidence, or max_rows cost implications, so the four undocumented parameters remain unexplained on both sides.

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 ('Build a lead list as a CSV download link'), enumerates the per-row columns, and names its two hard prerequisites. The CSV-download framing effectively separates it from search_places and get_place, though no sibling is named explicitly.

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?

'Needs a category and a location' gives the entry conditions, and the quota sentence hints this is a costly bulk operation rather than a browse call. But there is no explicit 'use search_places for interactive lookup, use this for bulk export' routing, so the agent must infer the choice relative to siblings.

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 covered. The description adds genuinely useful behavior beyond that: the shape of the return (matching ids, taxonomy position, US place counts) and the hierarchy rule that broader ids include all subcategories. It omits result limits/ordering, but that is a modest 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?

Two sentences, no filler, and the primary purpose plus the consuming tools are front-loaded. The hierarchy note is a single compact clause that earns its place by preventing misuse of parent ids.

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 to describe the return payload (ids, taxonomy position, place counts) and the inheritance semantics, which is what an agent needs to use results correctly. Only minor operational details, such as how many matches come back or whether they are ranked, are left unspecified.

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

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

There is a single required parameter with 100% schema description coverage, including concrete examples ("roofers", "dentist", "italian restaurant"), so the schema carries the semantic load. The description adds nothing about the query string itself, which is the expected baseline-3 outcome when coverage is high.

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 and resource ("Find category ids") and immediately names the two sibling tools that consume those ids (search_places / export_leads), so an agent can place it in the workflow without opening a schema. It is clearly distinct from get_place, search_places, verify_websites and export_leads.

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 makes the usage context explicit: this is the id-lookup step that must precede search_places and export_leads. That is a clear, actionable when-to-use signal. It stops short of explicit exclusions (e.g. when to skip it and call search_places with a plain-text query instead), so it is not a full 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 declare readOnly, idempotent, non-destructive, closed-world, so safety adds nothing. The description's real contribution is disclosing the payload shape — it tells the agent this returns a superset including sources, license, and a conditional website check, 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 sentence, front-loaded with 'Full record for one place' and then the field inventory. No filler, no restatement of the tool name.

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 field list does the work of describing the return value, so an agent knows what it gets. Minor gap: behavior for unknown or missing place_id (error vs. empty result) is unstated.

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

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

Schema coverage is 100% and the schema already explains that place_id comes from search_places or export_leads. The description adds no format, prefix, or lookup behavior beyond the schema, 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?

Names a specific resource and retrieval scope: 'Full record for one place', then enumerates the contents (contact fields, coordinates, category path, data sources/license, website check). This clearly separates it from the list-style sibling search_places, though no sibling is named explicitly.

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 by the singular 'one place' framing; the description never states when to call this instead of search_places or export_leads. The actual routing cue lives in the schema ('Place id from search_places or export_leads'), not the 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new context: the per-call result cap of 100, that results are compact, and that a total match count is returned. It does not explain sort order, the default limit of 25, or the offset ceiling.

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 in a logical order: what it does, what it requires and returns, then the escape hatch. No filler or restatement of the name.

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 13-parameter search tool with no output schema, the description covers result shape (compact rows plus total count), the hard precondition, and the pagination alternative. The gaps are pagination mechanics (offset vs the 100-result cap) and how the boolean filters change results, which an agent may need to reason about.

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 62%, with meaningful descriptions on city, near, category, postcode, radius_km and min_confidence, but limit, offset and the require_* flags are bare. The description compensates only indirectly by implying a 100-row ceiling and a location-or-name constraint; it says nothing about what require_email/phone/website do or how offset pages interact with the cap.

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), resource (US businesses and places) and the three axes it searches on (category, name, location). The US scoping and the explicit contrast with export_leads make it unmistakable among siblings.

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

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

Gives a clear precondition (at least one location filter or a name) and an explicit alternative for the deep-pagination case (export_leads). It doesn't say when to prefer get_place or that category ids must come from find_categories, so it stops just short of a complete routing guide.

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 and non-destructive, so safety is covered. The description adds value beyond that with the per-place billing model and the enumerated status taxonomy, which is the real behavioral payload of the tool. Caching behavior (30 days) is left to the schema rather than restated.

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: action first, status vocabulary second, cost/usage last. The parenthetical status list is compact and every clause carries information the agent needs; nothing is padded.

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 doubles as return-value documentation via the status enum, and it discloses the cost model. The remaining gap is edge-case behavior — e.g., what status is returned for a place with no website listed — which an agent might reasonably need.

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 place_ids (max 25) and force_recheck (ignore 30-day cache) are already fully documented. The description's phrase "status per place" hints that results are keyed per id, but adds no syntax or format detail beyond the schema — 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+resource ('Check whether each place's listed website is live right now') and enumerates the possible outcomes (live, live_bot_protected, redirected_elsewhere, page_not_found, dead_domain, unreachable). This distinguishes it from retrieval siblings like get_place and search_places without needing to open any schema.

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

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

"Use before outreach" gives a concrete trigger point, and "Each place checked counts as one call" warns about the cost of batching many ids. It lacks an explicit exclusion (e.g., when not to bother re-verifying, or an alternative tool), so it stops just short of the top score.

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