scanner

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 covered. The description adds domain context about what the dataset contains but discloses nothing about pacing, pagination, or the stateful conversation_id requirement that the schema imposes, so it adds only modest value beyond 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?

The core purpose is front-loaded, but the paragraph is dense and overstuffed with enumeration, and the trailing page-URL sentence does not help an agent decide or invoke. It is efficient enough but not tight.

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 useful work by spelling out the shape of the result (destination ranking, per-assistant and overall shares, headline shares), so an agent knows what it receives. Safety and idempotency are covered by annotations, leaving little meaningfully missing for this read-only analytics 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%, so all five parameters (city, limit, context, llm_model, conversation_id) are fully documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, 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?

It states a specific resource and scope: a league table of the destinations assistants link to in a city, broken down by assistant, marketplace, press, and overall, with share metrics. An agent can grasp the dataset, though no explicit verb is used and it does not distinguish itself from siblings like assistant_recommendations or what_assistants_say.

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 guidance, no prerequisites, and no reference to alternative tools. The only routing hint is the trailing URL patterns, which describe where humans can view pages rather than when an agent should call this tool.

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 the safety profile is fully covered elsewhere. The description adds useful behavioral context beyond that: it discloses the return shape (per question, per assistant, with links) and the two page paths. It does not mention pagination limits, result caps, or freshness.

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 dense sentence front-loads the resource and return contents, followed by a short URL line. The parenthetical query examples earn their place by illustrating the question dimension. Slightly overloaded with parallel clauses but 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 no output schema, the description compensates by enumerating what each result contains, which is the key missing piece. Five parameters are all documented in the schema at 100% coverage, including the unusual conversation_id contract. Gaps are minor (no coverage of result limits or how intent keys are discovered, though list_cities is cross-referenced for city).

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 detailed contracts for context, llm_model and conversation_id, so the schema does the heavy lifting. The description adds only the URL shape showing {slug}/{question}, which loosely maps to city and intent but gives no syntax or format detail 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?

The description names a specific resource (places that ChatGPT, Claude and Gemini name for a given question in a city) and enumerates the returned fields (places, which assistant named each, site link, booking link), which is far more than a restatement of the title. It does not, however, explicitly differentiate itself from close siblings such as what_assistants_say or assistant_destinations, so the agent must infer 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?

There is no when-to-use or when-not-to-use guidance and no alternative tool is named. The description implies the tool answers 'what do assistants recommend in city X for question Y', but an agent choosing between this and what_assistants_say or assistant_destinations gets no routing help.

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 genuine behavioral value by disclosing what the payload contains and that each change links to the business's report, plus alternate access surfaces (web page, Atom feed, JSON endpoint). It does not mention auth, rate limits, or pagination beyond the days parameter.

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 substantive answer to "what does this return?". The second sentence is a dense list of access formats that is slightly listy but each element (page, feed, JSON) is distinct and useful, so it earns its place without much 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 tool with no output schema, the description carries the return-content burden well by naming the change categories and the per-change report link. The analytics-only parameters (context, llm_model) are fully explained in the schema, so nothing an agent needs to call correctly 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 coverage is 80%, so the schema already documents city, days, context, and llm_model. The description only reinforces the time window implicitly through "over the last days" and the JSON example of days=30; it adds no new parameter syntax or constraints beyond what the schema provides. 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-resource pairing ("what changed in a city index over the last days") and enumerates the exact change categories returned (findings, grades, crawlers, channels, vendors, assistant answers). That is far more precise than the name/title alone, though it never explicitly names a sibling to contrast against, so it stops short of 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?

Usage is implied by the temporal framing ("over the last days"), which signals this is a delta/recent-changes view rather than a snapshot. However there is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as city_leaderboard or country_summary for static information.

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 safety is covered. The description adds the meaningful behavioral context that results are comparative ('compared with every index of the same kind') and enumerates the returned metric families, but says nothing about scope limits, pagination, or freshness.

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 entire description is one ~90-word run-on sentence built as a long metric list, with the actual purpose buried at the start in a relative clause and the URLs tacked on at the end. Nothing is front-loaded and the enumerated metrics are not grouped, making it hard to scan.

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 necessary work of enumerating the data it returns, and annotations cover safety. However, it omits that the call carries mandatory analytics/telemetry parameters and a stateful conversation_id handshake, which is unusual behavior an agent would benefit from being warned about up front.

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 all four parameters (city, context, llm_model, conversation_id) carry detailed schema descriptions, including the strict conversation_id contract. The description adds nothing about parameters, so the baseline 3 is correct.

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 communicates the subject matter (website-level statistics for a city index, benchmarked against same-kind indices) but never states a clean verb+resource. There is no differentiation from siblings like city_leaderboard, compare_cities, or city_changes, which plausibly return overlapping comparative data, so an agent cannot disambiguate from this text alone.

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 guidance, no prerequisites, and no named alternatives despite a crowded sibling set (compare_cities, city_leaderboard, country_summary). The two page URLs are appended without explaining what they are for, so the agent gets no routing signal.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail of what dimensions are returned (grade, menu format, direct channel, crawler blocking), but says nothing about scope limits, pagination, or the conversation_id chaining requirement, which is behavioral context the annotations do not supply.

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 filler, though it is a noun phrase fragment rather than a verb-led statement, which slightly weakens immediacy.

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 enumerates the returned fields, but it omits any indication of ranking direction, tie handling, or truncation behavior at the limit. It is adequate but not complete for a leaderboard 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 80%, with city, context, llm_model, and conversation_id all documented in the schema. The description adds no parameter detail at all, and the undescribed 'limit' parameter (default 50, max 500) is left to the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource (businesses in a city index) and the ranking criterion (Agent-Direct Score), plus the fields surfaced. It is clear what comes back, but it never distinguishes itself from siblings like rankings, compare_cities, or list_cities.

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?

No when-to-use, when-not-to-use, or alternative-tool guidance is present. An agent cannot tell from the description whether to pick this over 'rankings' or 'list_cities'.

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=true, idempotent=true, openWorld=false, so the safety profile is covered. The description goes further by detailing the returned dimensions (site scans, AI-crawler rejection share, grades, menus, channels, builders, vendors, monthly numbers) and the backing page URL, which is real behavioral context beyond 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?

Two sentences, well front-loaded: the comparison scope leads and input forms plus the page template follow. The metric enumeration is long but each item conveys what the tool returns, so it earns its space; a slightly tighter grouping would be ideal.

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 carries the burden of describing return content, and it does so thoroughly via the metric list. The analytics-only parameters (context, llm_model, conversation_id) are fully specified in the schema, so the description need not repeat them. Minor gap: no note on behavior when a slug is unknown.

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 the schema already documents every parameter including examples for a/b and the enum for kind. The description only restates that inputs can be slugs or city names with examples like 'lisbon, Porto, berlin-cafes-bars', adding marginal value over the schema's own example fields.

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 (compare) and resource (two city indexes) and enumerates exactly what dimensions are compared, so an agent understands the operation immediately. It does not, however, explicitly distinguish itself from close siblings like city_leaderboard, rankings, or country_summary, leaving the pairwise-vs-ranking distinction to inference.

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 explains accepted input forms ('index slugs or city names') but gives no when-to-use guidance, no exclusions, and no pointer to alternatives such as city_leaderboard or rankings. The agent must infer that this is for head-to-head comparison only.

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 externally. The description adds the useful behavioral fact that omitting the code returns all countries, plus documentation URLs, but discloses nothing about pagination, result size, or freshness/caching.

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 core information is front-loaded, but the body is a comma-run enumeration of return fields and the trailing documentation URLs dilute it. It is information-dense rather than wasteful, yet not tightly structured.

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?

There is no output schema, so the description carries the burden of describing returns, and it does list the aggregated metrics a caller can expect. Combined with the annotations covering safety, this is near-complete for a read-only summary tool; only pagination and list-size behavior are unaddressed.

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 are already documented in the schema, including the empty-value semantics of 'code'. The description restates the ISO-code/empty-for-all-countries behavior, adding no syntax or format detail beyond the schema — 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?

The description states a specific resource and scope: a country's aggregated indexes, enumerated field-by-field (sites scanned, direct share, crawler-blocked share, cities, kinds, vendors). It is clearly distinguishable from siblings like list_cities or vendor_report, though the phrasing is list-like rather than a single crisp verb+resource statement.

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 explains the two modes of use — pass an ISO code (PT, DE) for one country, omit it for every country with an index — which is genuine invocation guidance. However it never names an alternative sibling or states when a different tool (e.g. city_leaderboard, rankings) would be the better pick.

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 does add genuine provenance context beyond annotations — browser verification with timestamps, per-fact source and date, owner correction where claimed, and monthly read/follow counts — but says nothing about behavior on unknown or unclaimed domains.

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 content is front-loaded ('The direct record of a business'), and enumerating return fields is defensible absent an output schema. However, it is delivered as one dense ~90-word sentence with a dozen comma-separated items and an API URL tacked on, which is hard to scan rather than economically structured.

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 covers what the record contains, and the URL template plus 'Corrected by the owner where the business is claimed' round out the picture for a read-only domain lookup. It is only slightly short of complete, missing error/unknown-domain behavior.

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 domain, context, llm_model, and conversation_id. The description only adds the URL template (GET https://directindex.org/api/direct/{domain}), which confirms domain usage but adds little the schema does not already convey; 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 makes clear this returns the 'direct record of a business' and enumerates its contents (booking/ordering/menu links, hours, phone, address, verdicts, score), but the verb is only implied by 'The direct record' rather than stated as a retrieval action. It also does not differentiate itself from the close sibling find_direct_places, which presumably retrieves similar data a different way.

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 'links an agent should use instead of a marketplace' is a hint about the content's value, not guidance on when to call this tool versus siblings like find_direct_places, search_places, or get_site_report. No prerequisites, exclusions, or alternatives are named, leaving usage 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful context about ranking (Agent-Direct Scores first), the follow-link domain pattern, verified_at semantics, and 'unknown hours stay in, marked null'. However, it doesn't explain pagination, total counts, or the conversation_id protocol, which is partly in the schema. With annotations covering safety, a 3 is appropriate.

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 a single very long sentence followed by more sentences, and it front-loads the core purpose well. However, it's dense and packs many concepts (ranking, links, verification, terms, hours, follow links) into one run-on sentence, making it harder to parse than necessary. It earns most of its length but could be restructured for clarity.

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, no-output-schema tool, the description covers the core purpose, the ranking logic, key filters, and the URL pattern for follow links. It's fairly complete, though it could mention result limits or pagination behavior. The required context and conversation_id parameters are well-documented in the schema, so the description needn't repeat them.

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 92%, so the schema already documents all 13 parameters thoroughly, including enums and defaults. The description restates the query, lat/lon/radius_m, open_now, verified_only, and vendor semantics without adding format details beyond the schema. Baseline of 3 is correct when schema does the heavy lifting.

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: finding places that take direct bookings/orders on their own site, ranked by Agent-Direct Scores, with booking links. It differentiates from siblings like search_places by the 'direct, without a marketplace' framing, though it never names the sibling it competes with 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?

Gives clear context: 'Use it to recommend places a person can book or order from directly, without a marketplace.' It explains the optional query and filters but doesn't explicitly exclude cases where search_places would be a better choice, leaving some ambiguity about when to prefer one over the other.

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 readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds the genuinely useful trait that the return shape changes over time — status first, then the full report — and enumerates what the finished report contains, which the annotations cannot convey. It stops short of stating polling cadence or whether status calls are free.

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 front-loaded sentence covering the outcome first and the payload second. The parenthetical inventory is long but every item earns its place by telling the agent what to expect in the returned Markdown.

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 carries the burden of describing the return value, and it does so with a concrete content list. Safety is covered by annotations and all four parameters are documented in the schema, leaving only minor gaps such as nothing about error states for an invalid or expired token.

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 baseline is 3. The description echoes that the order is identified by its token, but adds no syntax or format detail beyond what the schema already states about the 32-character token and the analytics-only context/model 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?

Names a specific verb (get) and resource (deep report), and explicitly splits the two states an agent will encounter: order status while pending, and the finished Markdown report once done. It describes the report's contents, and the token link to order_deep_report clearly separates it from the sibling that places the order.

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 status-vs-finished phrasing implies the intended polling flow after order_deep_report, so an agent knows this is the follow-up call rather than a fresh order. It does not name explicit alternatives or exclusions, but for a single-purpose lookup tool the usage context is clear.

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 and destructiveHint=false, so safety is covered. The description adds genuinely new context: it returns a cached/latest report rather than triggering a scan, and enumerates the report's sections. It does not mention the stateful conversation_id handshake, but that is documented in the 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 tight sentence, front-loaded with the verb and resource, that also carries the precondition and content summary. 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, idempotent report fetch with no output schema, the description covers what is returned and the prerequisite scan. A brief note on report freshness or empty-result behavior would make it fully complete, but nothing essential 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 the schema already documents all four parameters, including the detailed context and conversation_id contracts. The description adds nothing about parameter meaning or format, 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 ("Return") and resource ("the latest Agent-Direct report for a domain"), plus the report's contents (findings, fixes, agent-discoverability checks). The "already been scanned" qualifier implicitly separates it from the scan_website sibling, though it never names that alternative outright.

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 "for a domain that has already been scanned" is a clear precondition telling the agent when this tool is applicable versus a scanning step. It stops short of naming siblings like scan_website or get_deep_report as the alternative, so the boundary is inferred rather than 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 declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds only that results include counts and status, without explaining what those fields mean or whether the list is paginated.

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 filler. It is efficient, though its brevity comes at the cost of the detail noted in other dimensions.

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?

There is no output schema, so the description should carry more of the return-value burden; "counts and status" gestures at it but leaves the notion of a "city index" and the status values unexplained. Adequate for a read-only list tool but with clear gaps.

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 three parameters (context, llm_model, conversation_id) are fully documented in the schema itself. The description adds nothing about parameters, which is acceptable at this coverage level.

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 (List) and resource (city indexes) plus the shape of the output (counts and status). However, the term "city indexes" is left undefined and the description offers no differentiation from city-oriented siblings such as city_leaderboard or city_changes.

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?

No when-to-use guidance is given. The description does not say when this should be chosen over siblings like compare_cities or country_summary, nor does it state any prerequisites or 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 it as a safe read (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful context beyond the structured fields: data provenance (restaurants' own websites), freshness ('the day they were read'), reliability ('how many prices a hand check found right'), and a scope caveat ('menu prices, not what a bill comes to').

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 opening clause is well front-loaded, but the body is one dense run-on cramming in ten menu items plus four metadata fields. It's informative but not efficiently structured; the item list could be summarized.

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?

There is no output schema, so the description carries the burden of describing returns, and it does so thoroughly: which items, which statistics, what metadata accompanies each figure. Combined with annotations covering the safety profile, an agent has enough to invoke and interpret it.

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 description only echoes the city semantics already in the schema ('Covers 13 European cities... without a city it lists them'). The context/llm_model/conversation_id plumbing params are handled entirely by the schema, so baseline 3 is correct.

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 resource (menu prices for a set of named items in a city) and even spells out the statistics returned (median and interquartile range). It's more specific than most siblings like city_facts or rankings, but it never explicitly distinguishes itself from them or names an alternative.

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: you call it to get menu prices, and 'without a city it lists them' documents the parameter-omission behavior. However there is no explicit when-to-use vs alternatives (e.g. compare_cities, city_facts), so the agent must infer the 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 only cover the safety profile (readOnly=false, idempotent=false, openWorld=true). The description goes well beyond them, disclosing the price, that nothing is charged until the user pays, that a Stripe checkout link is returned, that the report is written in about fifteen minutes after payment, that it is emailed, and that its status/text is retrievable by token.

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 purpose is front-loaded in the opening clause and every clause carries decision-relevant content (price, deliverable, return values, turnaround). It is still a single very long, comma-heavy sentence, which costs some readability, so it falls short of a 5.

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 carries the return-value burden well by stating it returns an order token and a Stripe checkout link, plus the post-payment lifecycle. It is complete for a checkout-creation tool; only minor wiring detail (e.g., the conversation_id sequencing) lives solely 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 description coverage is 100%, so the schema already documents every parameter (lang, email, domain, context, llm_model, conversation_id). The description adds no parameter-specific syntax or format detail beyond tying the email param to delivery, 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 (order) plus the exact resource and price (the paid deep report, 5 EUR, one-off) scoped to a business in a city index. It implicitly distinguishes itself from the read-side siblings by noting the report 'can be read by the token', but it never names get_deep_report or get_site_report explicitly, so sibling differentiation is inferential rather than stated.

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 audience and prerequisite are implied (a business in a city index, matching the domain param's requirement), and the cost/checkout flow makes the 'when' reasonably clear. However, it never routes the agent to alternatives such as get_deep_report for reading an existing report or get_site_report, and gives no explicit when-not condition.

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, not destructive, closed-world), so credit goes to what the description adds: the ranking thresholds (<100 scanned sites => unranked; <4/5 of own sites scanned => partly scanned) and the definition of each measure. That is substantive behavior an agent could not infer from annotations or 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?

Two dense sentences that front-load what is returned and then the two exception rules, which is the right order for a data-listing tool. Some parenthetical definitions are padded, but nothing 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?

There is no output schema, yet the description names the return fields (three shares, sample size, date) and the special listing states, which is the information an agent needs to interpret results. The only missing piece is any hint about result volume or pagination.

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 the enum values and their meanings, so the schema already carries the parameter burden and baseline 3 applies. The description's '?kind=' URL hint restates the kind parameter without adding semantics (e.g., defaulting behavior or effect of 'all'), so it does not earn above baseline.

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 (city indexes of a given kind) and exactly what is returned: three named measures plus sample size and date, with explicit edge-case flags for unranked and partly-scanned indexes. That is far more precise than a title restatement, though it never distinguishes itself from the near-sibling 'city_leaderboard' or 'compare_cities'.

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 explains content but not when to reach for this tool versus alternatives. With a sibling named 'city_leaderboard' that plausibly overlaps, the absence of any routing guidance ('use this when you need per-kind rankings rather than...') is a real gap. Usage can only be inferred from the topic.

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=false, idempotentHint=false, and destructiveHint=false, so safety is partly covered. The description adds real value beyond those: it discloses the 24-hour cache-reuse behavior and the 10-40s run time, 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 tight sentences, front-loaded with the core action and return value, then the caching/latency caveat. Every clause earns its place and nothing is padding.

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 return-value burden by naming score, grade, findings, and fixes, and it covers caching and timing. It stops short of stating persistence or follow-up expectations (e.g. conversation_id reuse), which is 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 all four parameters are fully documented in the schema itself and the baseline is 3. The description adds no param-level detail (e.g. URL format or context-param handling) beyond what the schema already states.

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 ("Scan a business website") and names the concrete outputs (Agent-Direct Score 0-100, grade, findings, fixes). It does not, however, differentiate itself from plausible siblings like get_site_report or get_deep_report.

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 (you scan a website to get its score); there is no explicit when-to-use/when-not or reference to an alternative tool. The caching rule and 10-40s latency are operational facts, not selection guidance.

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 new behavioral context: 50 results per page, ordering by Agent-Direct Score, a per-result report link, and that the call is free and returns no contacts — details no annotation 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 dense sentence front-loads the core purpose, matching modes, and filters, followed by a short return-format clause and the site URL. Every clause carries information, though the filter enumeration is slightly list-like and could be trimmed given the schema already names them.

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 11-parameter search with no output schema, the description supplies the essentials an agent would otherwise lack: result count per page, sort order, and that each hit links to its report. The analytics/context and conversation_id mechanics are fully documented in the schema, so no material gap remains.

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 73%, so the baseline is 3; the q, city, vendor, builder and finding parameters are already documented with examples in the schema. The description restates that same filter set (including finding examples) without adding syntax, combinability rules, or defaults, so it is roughly redundant with structured data.

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 businesses in the city indexes) with the two matching modes spelled out — name within a city, domain from any city. However, it never names or contrasts itself against the close siblings that could also surface businesses (find_direct_places, direct_record, assistant_recommendations), so an agent must infer 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?

The description encodes a real usage rule — a name query requires a city while a domain query does not — which is actionable guidance. But it offers no when-to-use/when-not guidance versus sibling lookup and reporting tools, and no exclusions; the reader must derive the calling context.

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, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds value by disclosing the report's field contents and the 'when a note exists' conditional for terms. It says nothing about failure behavior for unknown slugs or lookup cost.

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 core is a single dense, comma-chained sentence enumerating report contents, followed by a fragment about slug format. It is reasonably front-loaded with 'A booking or ordering vendor across the index' but reads as a run-on list rather than a structured statement of purpose plus usage.

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 enumeration is genuinely necessary and mostly complete, telling the agent what a call returns. Coverage gaps remain around vendor_terms disambiguation and unknown-slug handling, but for a read-only lookup with full param coverage this is close to sufficient.

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 every parameter, giving a baseline of 3. The description only reinforces the slug parameter with additional examples (sevenrooms, thefork, toast) and a reference URL, which is marginal but slightly additive.

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 clearly establishes that this tool returns a per-vendor report and enumerates the specific data points it covers (usable-site counts, average score, A/B share, browser action test, cities, example sites, terms). That is a specific resource with defined scope. It does not, however, distinguish itself from the sibling vendor_terms even though it mentions vendor terms as one of its own outputs.

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, when-not-to-use, or alternative routing. The agent must infer that this is the tool for vendor-level aggregate stats versus city/place/report tools. The overlap with vendor_terms is never resolved, so a user asking about a vendor's agent terms could reasonably be routed to either tool.

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 a safe read-only, idempotent, non-destructive operation, so the bar is lower. The description adds genuinely useful behavioral context beyond that: the enumerated outcome values (allowed, partners only, banned, not stated) and the fact that the vendor's own page and the date the terms were read are returned.

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?

Dense but front-loaded: the verdict concept comes first, then scope behavior, then the usage trigger. The "Without a vendor" fragment is slightly clipped, but no sentence 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?

There is no output schema, so the description must explain returns, and it does — the four verdict values plus the source page and read date. Combined with 100% schema coverage on the analytics parameters, an agent has enough to call this 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 coverage is 100%, so the baseline is 3. The description goes further by defining what the optional vendor parameter does when omitted — "Without a vendor: every researched vendor" — which is semantics not present in 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?

States a specific resource and the fact being reported: whether a booking/ordering vendor's terms permit an AI agent to book or order, with the four possible verdicts spelled out. It clearly distinguishes this from a generic report lookup. It stops short of naming the obvious sibling vendor_report to differentiate.

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 it before sending a person to book or order through a vendor on an agent's behalf" gives an explicit trigger condition, and the no-vendor case is described. No exclusions or alternative tools (e.g. vendor_report) are named, so it stops short of full routing guidance.

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 agent knows this is a safe, repeatable read. The description adds the constraint that only indexed, previously-asked-about businesses qualify and points to a report URL, but says nothing about auth, rate limits, or result freshness. A 3 fits given the safety profile is already covered.

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 dense but well-organized sentence, front-loaded with the core resource ('What ChatGPT, Claude and Gemini answer about one business') and using a parenthetical list to enumerate verdict types. The trailing precondition and URL earn their place. Slightly packed, but nothing 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 describing what comes back — verdicts, quoted answers, named questions, redirect rationale — so the agent knows the shape of the result. The city-index precondition and report URL round it out. Missing only a note on freshness/update cadence, keeping it from 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%, so the schema already documents domain, context, llm_model and conversation_id — including the strict conversation_id reuse rule. The description adds no parameter-level meaning beyond what the schema provides, so the 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 resource (what ChatGPT, Claude and Gemini answer about one business) and enumerates the returned content: per-question verdicts, quoted answers, questions the business was named for, and a redirect sentence. This is far more specific than a tautology. It does not, however, explicitly distinguish itself from the related siblings assistant_recommendations and assistant_destinations, so it falls short of 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?

There is an implicit precondition — 'For businesses in a city index that have been asked about' — which tells the agent the data source and a qualifying condition. But it never states when to prefer this tool over sibling assistant_* tools, nor any exclusions. Usage is implied, not spelled out.

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