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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description is not carrying that burden. It adds genuinely useful operational context the annotations cannot convey: 30-90 seconds per app, per-app cost of $0.05 ($0.04 on Gold), and the contents of the returned report. It does not cover failure modes or partial-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?

A single dense paragraph, well front-loaded: purpose and scope first, accepted input formats second, use cases third, and cost/latency last. Every sentence carries information, though the output enumeration and input-format list make it slightly long.

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 usefully enumerates what the report contains, and it adds the latency and cost dimensions an agent needs for a long-running paid job. The main remaining gap is that it does not clarify the relationship to get_app_reviews or what happens when an app cannot be resolved.

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 three parameters are already documented in the schema, and the description largely restates the accepted identifier formats for 'apps'. It adds no syntax or format detail beyond what the schema provides for country or max_reviews_per_app, 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?

The description names a specific verb+resource ('AI analysis of the latest App Store and Google Play reviews') and enumerates the exact analysis outputs (top bugs, feature requests, critical issues, competitor mentions, sentiment, rating distribution, versions). It is highly specific, but it never explicitly distinguishes itself from the closely related sibling get_app_reviews, which an agent must choose between.

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 states clear usage contexts ('product research, competitor analysis and release monitoring') and notes the scale limit of up to 5 apps, giving the agent a solid sense of when the tool applies. It stops short of naming when not to use it or pointing to get_app_reviews as the raw-data alternative, so the routing decision is left partly 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 cover the safety profile (readOnly, openWorld, non-destructive, non-idempotent), and the description adds genuinely new behavioral context: 5–20 seconds per keyword and explicit per-keyword and per-run pricing. It stops short of describing failure modes or rate limits, but the latency and cost disclosure is real value 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?

The purpose and output scope are front-loaded in a single dense sentence, and the usage sentence follows logically. The pricing clause, with per-date tiers and currency figures, is heavier than strictly necessary but is still information an agent may need to relay about cost.

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 by enumerating the fields the check reports (overview presence, citation position, competing domains, brand mention, overview text, organic rank, deltas). Given annotations plus the six fully documented parameters, an agent has enough to call it, though error/empty-result behavior is not covered.

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 six parameters, making 3 the correct baseline. The description reinforces that the domain is 'yours' and that brand mentions and cited competitors are tracked outputs, but it adds 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?

States a specific verb and resource (check Google AI Overviews for keywords) and enumerates the scope of what is determined: overview presence, citation position, competitors cited, brand mentions, organic rank, and deltas. It is distinguishable from most siblings, but the closely related sibling check_ai_visibility is never mentioned or differentiated, 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?

It gives a use context (AEO/GEO audits and monitoring), which is more than implied usage, but offers no when-not guidance and no routing against alternatives even though check_ai_visibility is an obvious candidate. Usage direction is present but unqualified.

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

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

Annotations already declare readOnly, openWorld and non-idempotent, so the safety profile is covered; the description goes further by disclosing runtime (1-3 minutes) and a concrete per-answer pricing model ($0.05/$0.04 plus $0.50 per report), which is real decision-relevant behavior for an agent. It does not mention auth or rate-limit characteristics.

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 definition is front-loaded with purpose and output contents before cost and timing, and every sentence carries information. It is somewhat long, but the length is justified by the number of returns and pricing details it must convey.

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 full burden of explaining returns, and it does so by enumerating mention, rank, citation, competitors, sentiment, snippet and sources. Combined with timing and pricing, an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds value by naming the engines behind the enum values and clarifying the metering unit ("each prompt on each engine is one answer checked"), plus flagging the extra charge tied to create_report.

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: ask AI assistants the customer's questions and check whether they mention/cite the brand, and it enumerates the returned signals (mention, rank, citation, competitors, sentiment, snippet, sources). It is very clear on its own, but it never distinguishes itself from the sibling check_ai_overview_citations, which sounds closely related.

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 for AI search visibility and share-of-voice tracking" implies the usage context but gives no explicit when-not condition and names no alternative tool, even though check_ai_overview_citations sits in the same sibling list. The cost/latency notes help an agent decide to call it, but routing guidance is absent.

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, openWorld, not idempotent); the description adds the operational facts an agent actually needs — 1–3 minute runtime because each website is visited, per-lead billing at $0.03 ($0.024 Gold), and that max_results drives cost. That is substantive context beyond structured fields.

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?

Front-loaded with purpose, then the return fields, then usage examples, then operational caveats. Four sentences, each carrying distinct information, with 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?

With no output schema and 11 parameters, the description compensates by enumerating the returned fields (name, category, address, phone, email, website, rating, review count, socials, opening-date estimate, unclaimed flag, lead score) and by disclosing cost and latency. Nothing an agent needs to call this 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 description coverage is 100%, so each of the 11 parameters is already documented. The description reinforces a few of them (email found on the website, no-website/recently-opened/review-count filters, AI outreach drafts) but adds no syntax, defaults, or constraints beyond what the schema provides.

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 ('Find local businesses on Google Maps'), names the scope ('any country'), and implicitly distinguishes itself from the sibling find_uk_business_leads by covering global coverage rather than UK-only. An agent can route correctly without opening the schema.

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

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

Provides concrete invocation examples ("dentist" in "Austin, TX"), names the filter categories available, and discloses time/cost so the agent can judge whether to call it. It does not explicitly state when to prefer it over the UK-specific sibling or other search tools, so it falls short of full when/when-not 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/openWorld/idempotent=false/destructive=false, so the safety profile is covered. The description adds two operational facts an agent must plan around: latency ('about 1-3 minutes for 10 leads') and per-lead billing cost ($0.05, $0.04 on Gold), which is meaningful context beyond structured fields. It does not cover failure modes or what happens when Companies House matching fails, keeping it at 4.

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?

Front-loads what the tool returns, then usage, then the two cost/latency facts an agent needs before committing. Four sentences with no filler, though the 'everything find_local_businesses returns plus...' clause is slightly dense.

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 and the match-confidence rating, which is exactly what the description must carry. Combined with cost, latency, geographic scope and target use case, an agent has everything needed 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 description coverage is 100%, so the schema already documents all 13 parameters with examples and defaults. The description only echoes two of them at a high level ('search UK cities or postcodes', 'any business type') and adds no syntax or format detail. 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?

States a specific verb+resource (UK business leads from Google Maps, enriched via Companies House) and enumerates the differentiating fields (director name, company number, incorporation date, company age, SIC codes). It explicitly positions itself against the sibling find_local_businesses ('everything find_local_businesses returns plus...'), so an agent can pick between them without opening a 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 it for UK B2B prospecting' gives clear usage context, and the framing against find_local_businesses implies when the extra enrichment is or isn't needed. It stops short of an explicit when-not rule (e.g. 'use find_local_businesses if you don't need director data'), so it is clear but not fully 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds genuinely new operational facts: newest-first ordering, a 200-per-call cap, and explicit per-ad pricing ($1/1,000 ads, $0.80 on Gold+). The non-idempotent ordering claim is consistent with idempotentHint=false, so there is no contradiction.

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?

Front-loaded with the resource and return contents, then lookup methods, then cost – a sensible order. It is a single dense paragraph and the enumerated return-field list is slightly long, but 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 no output schema, the description carries the return-value burden and does so thoroughly (format, dates, days running, headline, texts, URLs, images, video). Combined with the cost disclosure, ordering, and cap, an agent has everything needed 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%, so every parameter (advertiser, format, region, max_results, include_ad_content) is already documented in the schema. The description restates lookup modes and the 200 cap but adds no syntax or semantics beyond structured fields, 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 ('Every ad an advertiser runs on Google Search, YouTube, Display and Shopping') with the data source named (Google's Ads Transparency Center). Distinct from siblings like search_google_shopping (product listings) and search_google_images/videos (organic search), so an agent can route correctly without opening a 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?

Gives an explicit use case ('competitor ad research and creative inspiration') and describes the input modes for lookup, plus filters by country and format. However it never states when NOT to use it or names an alternative sibling tool, so the guidance is clear context rather than routing rules.

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

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

Annotations already declare readOnlyHint, openWorldHint and non-destructive behavior, so safety is covered. The description goes beyond them with two genuinely useful operational facts an agent cannot get from structured fields: a hard cap of 500 reviews per call and explicit Apify cost ($0.08/1,000 reviews, $0.05-$0.07 on paid plans).

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?

Four tight sentences, front-loaded with what the tool returns before moving to accepted inputs, filtering, limits and cost. Dense and useful, though some of the input/limit material duplicates the schema rather than earning its place.

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

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

With no output schema, the description correctly enumerates the return fields; it also covers input formats, filtering, sort options, per-call limits and pricing. Nothing an agent needs to invoke it correctly is missing, aside from sibling routing which is scored elsewhere.

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 every parameter is already documented with defaults, enums, ranges and examples. The description's parameter mentions (input formats, star filtering, country/language, 500 cap) largely restate the schema rather than adding syntax or edge-case meaning, 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?

The description names a specific verb+resource (fetch app reviews) and enumerates the returned fields (rating, title, text, date, reviewer, version, votes, developer reply), so the agent knows exactly what it gets. It does not distinguish itself from the sibling analyze_app_reviews, which is the obvious confusion risk.

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: 'Filter by star rating (e.g. 1-2 stars for complaints)' hints at the complaint-mining use case, and the accepted input formats are listed. But there is no when-to-use/when-not guidance and no routing to analyze_app_reviews for aggregate analysis.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful non-schema behavior: explicit cost on the user's Apify account ($1 per 1,000 keyword reports, $0.50 per 1,000 trending searches) and the 'Breakout' flag semantics in results. It doesn't discuss latency or failure modes, 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?

Front-loads what the tool returns, then the configurable dimensions, then the use case, then pricing. Dense but every clause carries information; the pricing sentence is long but is the only place that cost is disclosed.

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?

No output schema exists, so the description carries the burden of explaining return values — and it does, listing the trend metrics, regions, related searches and Breakout flags. Combined with full schema coverage and annotations, an agent has everything needed 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 coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by explaining the 0–100 comparison scale, geo granularity examples (US, GB, US-CA), the time-range span ('past hour to all time'), and the search types — reinforcing rather than merely repeating field names.

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: retrieve Google Trends data for up to 5 keywords, with an explicit enumeration of the returned signals (interest over time, average/latest/peak, regions, related searches). This is clearly distinguishable from siblings like get_trending_searches or the search_google_* family.

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 usage context ('demand and seasonality research', 'compare brands or topics') and the conditions it supports (country/region, time range, search type). It does not, however, name an alternative tool or state when NOT to use it versus get_trending_searches, so it stops 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.

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

Annotations already establish readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds genuinely new context beyond the annotations: the operation is free, and it only reads results already paid for, which matters for an agent deciding whether to poll.

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, front-loading the core action and then the trigger condition and input source. Each sentence carries distinct information with no 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?

No output schema, and the description covers what comes back at a high level (status and results) plus the pagination parameters exist in the schema. For a simple read tool this is close to sufficient, though it doesn't say what a completed vs. still-running status looks like in the response.

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, but the description adds provenance semantics for run_id ('the run_id printed by the tool that started the run') that the schema only states more tersely. limit/offset are left to the schema, which documents them adequately.

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

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

Specific verb+resource: fetch status and results of an Apify run, explicitly scoped to runs 'started by one of this server's tools'. It also names concrete triggering cases (long-running lead or AI-visibility searches), so an agent can tell it apart from every sibling search tool, which initiate work rather than retrieve it.

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 for when to call it: when a prior tool returned while a run was still in progress, and instructs the agent to pass the run_id from that tool's output. No explicit 'when not to use' or named alternative, but the selection condition 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 cover safety (readOnly, non-destructive, openWorld) but not cost; the description uniquely discloses pricing ($1 per 1,000 keyword reports, $0.50 per 1,000 trending searches), which is critical for a paid, per-result billed tool. It also mentions the available time windows. It does not mention rate limits or result pagination, but adds meaningful context 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?

Front-loads the purpose in the first sentence and packs field list, windows, use cases, and cost into a compact block with no filler. The cost line is slightly dense but earns its place given billing implications.

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?

A 5-parameter optional-only tool with no output schema is well served: it describes return fields, time-window constraints, and billing. However, it never explains what the numeric 'increase' means or the format of 'start time', and lacks pagination guidance, which would be useful for an agent consuming results.

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 parameters (hours, country, max_results, only_active, include_news) are fully documented in the schema. The description echoes the time-window options but adds no new parameter syntax or constraints. Baseline 3 applies 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?

States a specific verb and resource ('What's trending on Google right now in a country') with an analogy to trends.google.com/trending that immediately conveys the data shape. It enumerates the returned fields and is easily distinguished from siblings like get_google_trends (interest-over-time) versus this real-time trending list.

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

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

Gives concrete use cases (real-time monitoring, news-jacking, content ideas) that tell the agent when this is the right tool. It doesn't name alternatives like get_google_trends or search_google_news, so the agent must infer routing, but the 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?

Goes well beyond the annotations: caption-priority ordering, best-effort translation with YouTube rate-limiting, error status and no billing for captionless videos, and explicit pricing ($1.50/1,000, $1.20 Gold+). This is exactly the extra behavioral context annotations cannot 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 dense paragraph, but it is front-loaded with the core purpose and input forms, and every sentence (language priority, billing, pricing) carries information. Slightly long and run-on, 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 covers return shape (title, channel, duration, caption language, word count, timestamps) and failure behavior, so an agent has everything needed to call it and interpret results.

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 already 100%, so the baseline is 3, but the description adds real meaning: it clarifies the accepted URL/ID/Shorts/youtu.be/channel/playlist forms and that channel or playlist URLs yield their latest videos, which ties directly to max_videos_per_channel.

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 the transcript (captions) of YouTube videos') and enumerates the returned fields and accepted input forms. It is clearly distinguishable from the sibling search_google_videos tool because it is about captions of a known video, not video 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?

Explicitly names intended uses ('summarise, quote, fact-check or search inside videos') and states the fallback behavior (manual captions first, then auto-generated; translation best effort). It does not, however, say when NOT to use it or point to an alternative sibling 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 only cover the safety profile (readOnly, openWorld, non-idempotent, non-destructive); the description adds the operationally critical details an agent needs — 5–20 second latency and explicit per-flight billing cost ($0.20/1,000 flights), which is essential for choosing max_results.

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?

Front-loaded with purpose, then returns, mode behavior, usage, latency and cost. Every sentence carries distinct information; the return-field list is justified because no output schema exists.

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 10-parameter, read-only, open-world search with no output schema, the description supplies the return shape, default trip mode, expected latency, and billing model — everything an agent needs to call it correctly and size its request.

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 every parameter including defaults, ranges, patterns and enums is already documented. The description's parameter notes (one-way default, return_date meaning round trip, omitted departure_date) largely restate the schema, so it meets the baseline without adding new syntax or constraints.

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 with scope: 'Search Google Flights for one route and date.' The enumerated return fields (prices, airlines, times, CO2, best-flight flag) make it unmistakably distinct from siblings like search_hotels or search_google_shopping.

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 use context ('for flight prices, schedules and the cheapest or fastest options between two places') and a mode rule ('One way by default; set return_date for round-trip prices'). It stops short of naming alternatives or stating when not to use it, so it is clear but not complete.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, so safety is covered. The description goes further with latency ('typically a few seconds'), a hard cap (100 images), billing cost ($0.25/1,000, $0.20 Gold+), and a licence-reuse warning — substantive operational 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?

Front-loaded with purpose and returns, then filters, then limits/cost. Every sentence carries information, though the inline enumeration of image types ('photo, clipart, line art, face, animated') is redundant with the schema enum.

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 naming every returned field (full-size URL, width/height, thumbnail, source page URL/title/site). Combined with latency, per-search cap, pricing and licensing notes, an agent has everything needed to call and interpret the 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 each filter has its own enum documentation, so the schema does the heavy lifting. The description restates the filter dimensions (size, colour, type, time, rights) and partially duplicates the image_type enum values, adding little beyond what is already structured.

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

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

States a specific verb (Search) and resource (Google Images) and immediately describes the returned artifact, so an agent can distinguish it from siblings like search_google_videos or search_google_shopping. No ambiguity about what the tool does.

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 name and the enumerated filters, but there is no explicit when-to-use framing and no routing away from sibling search tools (e.g. videos, shopping, news). The licence caution is useful but is a post-retrieval note, 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 cover the safety profile (readOnlyHint, openWorldHint, idempotentHint=false, destructiveHint=false), and the description adds valuable operational context beyond them: return fields, the Google redirect being resolved, latency ("typically a few seconds"), the 100-article cap, and pricing ($1 per 1,000 articles). It does not address auth/credential needs or rate limits, keeping it below 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?

Front-loaded with what the tool does, then return shape, filtering options, use cases, and finally limits/cost. Every sentence adds an actionable fact and none is redundant.

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 return fields; with annotations present, it still contributes latency, cost, and result caps. Between the fully documented schema, annotations, and description, an agent has everything needed 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%, so the schema already documents all six parameters (including both enums and defaults), making 3 the baseline. The description's filter/sort mentions largely restate enum values, though the billing note for max_results marginally enriches it.

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 Google News") plus the input types (topic, company, person), which inherently separates it from sibling verticals like search_google_shopping, search_google_images, and search_google_videos. An agent can tell what it does and which domain it covers without opening the schema.

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

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

Explicitly names use cases ("current events, company and competitor news monitoring, and research"), giving clear context for when to reach for it. It stops short of naming a when-not condition or a specific alternative sibling to prefer, so it is strong context without 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 the safety profile (readOnly, openWorld, non-idempotent, non-destructive), and the description layers on real behavioral context: the returned field set, ~50 products per search, currency scoping, 'a few seconds' latency, and explicit billing ($1/1,000 products). That cost/latency disclosure is exactly what annotations cannot 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?

Front-loads purpose, then returns, then usage, then operational facts, with no wasted sentences. The return-field list is long but informative; overall tight and well ordered.

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 and does so fully (title, prices, store, delivery, rating, link), plus volume, latency, currency, and cost. Nothing an agent needs to call it 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 100%, so each parameter is already documented with examples and constraints. The description's mention of country currency and per-search volume reinforces but does not extend the schema meaningfully, 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?

Opens with a specific verb+resource ('Search Google Shopping for a product in any country') and is clearly distinct from siblings like search_google_news, search_google_images, and search_google_videos. An agent can route to it without opening the schema.

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

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

Explicitly states the use cases ('price comparison, finding where to buy, and competitor or market price research'), giving clear context for selection. It does not name a specific alternative or a when-not-to-use condition, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), so the description earns credit for adding what they do not: the returned fields (title, URL, platform, channel, duration, publish date, snippet, key moments, Shorts flag), the 100-video ceiling, and the cost of $1 per 1,000 videos. It does not discuss pagination or rate limiting, so it is strong but not exhaustive.

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?

Six short sentences, front-loaded with purpose then returns then filtering then limits then cost, so the essentials come first. Slightly list-dense, but no sentence is wasted and nothing is buried.

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's enumeration of result fields is load-bearing and present. Combined with the result cap and billing note, an agent has everything needed to size the call and interpret the response.

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 every parameter (time, duration, country, language, max_results) is already documented with enums, defaults and bounds. The description only echoes 'filter by time and length' and 'up to 100 videos per call', adding no syntax or semantics beyond the schema. Baseline 3 applies 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?

States a specific verb and resource ('Search Google's video results') and enumerates the covered platforms (YouTube, TikTok, Vimeo, news sites), which distinguishes it from the sibling get_youtube_transcripts and from search_google_images/news/shopping. An agent can route correctly without opening the schema.

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

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

Gives clear context for use ('to find videos on a topic beyond YouTube's own search') and notes the time/length filtering affordance. It does not state explicit exclusions or name a sibling tool as the alternative, so it stops short of a full when/when-not routing rule.

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, openWorld, non-destructive, non-idempotent); the description adds the operationally important traits: 20-hotel cap, 5–20 second latency, per-result billing at $1/1,000 hotels, and the non-obvious behavior that omitting dates makes Google choose them. That is substantial disclosure beyond structured fields.

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?

Front-loaded with purpose and scope, then return fields, then date/filter guidance, then limits and cost. Every sentence carries information an agent needs; nothing is restated from the schema or 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 compensates by enumerating the return payload (name, star class, rating, review counts, prices with/without taxes, total, description, nearby places, website, coordinates, link). Combined with per-result billing and latency, an agent has everything needed to call and interpret this 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 100%, so the baseline is 3, but the description adds real meaning: the check_in/check_out pairing determines whether prices are exact or Google-chosen, and the filters are framed as narrowing criteria. It does not clarify the currency-vs-country interaction, which stays 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 verb and resource (Search Google Hotels) plus the supported location granularity (city, neighbourhood, landmark), and enumerates the returned fields. This clearly distinguishes it from siblings like search_google_shopping or find_local_businesses, which target different resources.

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

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

Gives concrete usage context: set check_in/check_out for exact prices, otherwise Google picks dates; how to filter by rating, stars and max nightly price. It does not name an alternative tool or state when NOT to use this one (e.g. vs. find_local_businesses for non-hotel lodging), so it stops short of a full routing rule.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: billing ($2/1,000 jobs, $1.50 on paid plans, plus $0.03 per search), a per-call cap of 100, and the aggregated source set. It omits auth requirements and whether results are cached or live.

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?

Front-loads the resource and its coverage, then moves to return shape, filters, limits and cost in a logical order. The enumerated return fields are dense but earn their place because no output schema exists. Slightly long, but no sentence is 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 the returned fields (title, company, location, remote flag, source, posting date, employment type, parsed salary, excerpt, qualifications, apply links). All 7 parameters are documented in the schema, and billing/limits are disclosed. Nothing an agent needs to call this 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 description coverage is 100% with enums on country, date_posted and employment_type, so the schema already carries full parameter meaning. The description only restates the filter dimensions (date posted, employment type, remote) and the 1–100 range without adding syntax or format detail. 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 (Search) and resource (Google Jobs) and immediately scopes it: aggregates listings from LinkedIn, Indeed, Glassdoor and company sites across 26 countries. This is unambiguously distinct from every sibling (search_flights, search_hotels, search_google_shopping, etc.), which cover other verticals.

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?

Explains the available narrowing options (date posted, employment type, remote only) and the 100-job ceiling, and the cost line implicitly tells the agent to request only what it needs. It stops short of stating when this tool is preferable to a sibling or any exclusion, but the sibling set has no overlapping resource, so the gap is minor.

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