Puley

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

Beyond the annotations, the description discloses a quota cost ('Counts toward account limits'), a persistence side effect ('saves the report in Puley history') that explains why readOnlyHint is false, and a data-fidelity rule ('Unavailable source data is not inferred'). It does not cover failure behavior for private or nonexistent accounts, which keeps 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?

Two sentences, front-loaded with the purpose and then the operational caveats. Every clause carries information an agent needs; nothing is redundant with the title.

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

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

For a two-parameter tool with no output schema, the description covers what is returned, the cost, the persistence effect, and the no-inference rule. The remaining gap is error handling and accepted input formats, which is minor but not negligible.

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 0% for two required parameters, so the description must compensate. It partially does by implying the platform values ('TikTok or Instagram') and restricting username to public accounts, but it gives no format guidance such as whether a leading '@' or URL is accepted.

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

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

The description names a specific verb and resource ('A report on a public TikTok or Instagram account') and enumerates the returned metrics: followers, typical views or likes, and standout posts. That distinguishes it from sibling tools like find_channels, search_posts, and read_with_account, though no sibling is named explicitly.

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

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

Usage is implied by the 'public account' constraint and the note that it counts toward account limits, which signals a costlier operation than a simple read. However, there is no explicit when-to-use/when-not guidance and no named alternative for cases where a cheaper lookup would suffice.

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 flag a non-read-only, open-world, non-destructive call, and the description usefully explains why: results are 'Saved in the user's Puley history', disclosing the persistence side effect. It also describes the return content (top recommendation, whether the business is named, quoted sites), valuable since there is no output schema. It omits latency/cost implications of querying two external models.

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, but the body is a single sprawling sentence with awkward phrasing ('with web search on as ChatGPT and Gemini answer people') and parameter notes tacked on inline. Every element is relevant, yet the packaging makes it harder to scan than it needs to be.

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 four-parameter tool with no output schema, the description covers what the tool does, what it returns, and the persistence side effect, which is close to complete. The gaps are the undocumented 'country' parameter and the absent comparison with 'get_recommended_by_ai'.

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?

With 0% schema description coverage the description must carry all parameter meaning, and it largely does: 'what' gets concrete examples (CRM for small businesses, dentist in Austin TX), 'business' is name or website, and 'questions' substitutes the user's own questions capped at three. Only 'country' (default US) is left undocumented.

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 concrete verb chain and resource: it asks OpenAI and Google models (with web search) three buyer-style questions and reports who is recommended first, whether the business is named, and which sites were quoted. That is far more specific than the name alone. It does not, however, distinguish itself from the very similar sibling 'get_recommended_by_ai', leaving an agent unsure which of the two to call.

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 scenario (a business owner checking AI visibility), and 'questions: the person's own questions instead' hints at a variant mode. But there is no explicit when-to-use, when-not-to-use, or comparison against the nearly identical 'get_recommended_by_ai' sibling, forcing the agent to infer.

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?

The description resolves the puzzle left by readOnlyHint=false on an otherwise read-shaped tool: 'Uses one read and saves the result in the user's Puley history.' That discloses both a credit cost and a persistent side effect the annotations only flag abstractly. It is consistent with the annotations (no contradiction) but does not cover failure modes or what happens on an unsupported domain.

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 the returned fields are front-loaded in the first sentence, with the parameter format and side effect following. It is dense but every clause carries information; the only cost is that the first sentence is long and would read better split.

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

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

With one parameter, no output schema and no enum constraints, the description supplies everything an agent needs: what it answers, what it returns, accepted input formats, and the cost/side-effect of calling it. Nothing material is left to inference for a tool of this complexity.

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 0%, so the description carries the full burden and does so: it specifies accepted inputs as an Amazon link across nine explicit domains or a 10-character ASIN. That is exactly the format detail an agent needs to construct a valid call, and it is unavailable anywhere 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?

The description names a specific resource and source ('the product's price history from camelcamelcamel') and enumerates exactly what it returns (lowest/highest ever and when, average, current, split across Amazon/third-party new/used). That is far more specific than a restated name. It stops short of 5 because it never differentiates from near-neighbour siblings such as resale_prices or should_i_sell, which an agent could plausibly confuse it with.

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 opening framing ('Whether an Amazon price is a good deal right now') implies the decision-support use case, so the agent can infer when to reach for it. However, there is no explicit when-not guidance, no mention of alternatives, and no prerequisites stated. Usage is implied rather than prescribed.

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?

The description adds real context beyond annotations: it explains the credit cost ('uses one read') and the write side effect ('saves the result in the user's Puley history'), which justifies the readOnlyHint=false. However it omits other behavioral traits such as error handling for unknown chart values, freshness/latency, or what the saved history entry looks like.

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, front-loaded with the resource and followed by the parameter semantics; every clause carries information. The long comma-separated enumeration of chart values is slightly hard to scan but earns its place given the absence of an enum in the schema.

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 3-parameter, no-output-schema tool, the description covers what is fetched, the fields returned per entry, all three parameters, and the credit/history side effect. It stops short of defaults and refresh timing, which is a minor gap rather than a blocking one.

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?

With 0% schema description coverage the description carries the whole burden and mostly succeeds: it documents country as a two-letter code with examples (us, gb, za, jp, br), limit as capped at 100, and chart via the enumerated chart names. Only depth is missing — the numeric default of limit and default country are not restated, and it does not say what happens if an unsupported chart string is passed.

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 the exact resource (Apple's chart feed) and enumerates the concrete chart types plus the fields returned per entry. It is clearly distinguishable from feeds like best_sellers or netflix_top10, though it never explicitly contrasts itself with those siblings.

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

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

Usage is implied by the resource ('right now' charts, any country) but there is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. An agent must infer that this is the Apple-specific chart tool rather than a general best-seller lookup.

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?

The description adds real behavioral context beyond the annotations: 'Uses one read and saves the result in the user's Puley history' explains why readOnlyHint is false despite the read nature, and 'right now' is consistent with openWorldHint=true. No permissions, rate limits, or failure modes are covered, so it stops short of 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?

The core purpose and return fields are front-loaded, and the long department/country lists earn their space because the schema has no enums. The prose is somewhat run-on with embedded lists that could be formatted more scannably.

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 lists the fields a result contains and discloses the history side effect, which is enough to call it confidently for a simple three-parameter read tool. The unexplained 'limit' parameter and lack of pagination/maximum guidance are the remaining 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?

With 0% schema description coverage and no enums, the description carries the parameter burden well by enumerating valid department values (kitchen, home, electronics ... everything) and country store codes (us, gb, de, ca, au, in, jp, fr, it, es, mx, br, za, ae...). The 'limit' parameter is never explained, leaving the number of returned products to inference.

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 ('Amazon's Best Sellers right now for a department in any Amazon country') and enumerates the returned fields (rank, name, star rating, number of ratings, price, link). It does not distinguish itself from plausible siblings such as amazon_price_history, search_marketplace or resale_prices, which keeps it from 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 offers use-case guidance ('Shows what's selling, for gift ideas or product research'), which implies when to reach for it. However, there are no exclusions, prerequisites, or named alternatives among the many price/marketplace siblings, leaving the agent to infer when another tool is a better fit.

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?

The description adds real context beyond the annotations: output ordering ('strongest first'), the metric ranges (authority 0-100), the exact comparison semantics, and the side effect 'Saved in the user's Puley history' — which explains why readOnlyHint is false despite this being a lookup tool. It stops short of noting that the tool is open-world/networked and may be slow or rate-limited, which the openWorldHint implies.

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

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

Two sentences, both loaded with information: the base behavior first, then the compare branch, then the persistence note. No filler or restatement of the tool name.

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

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

With only two parameters, no output schema, and no field descriptions, the description does a good job describing both the inputs and the shape of the return. A minor gap is the absence of any indication of how many referring sites are returned or how the list is bounded.

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 0%, so the description must carry the parameter meaning, and it largely does: domain is the site being analyzed, and compare_with is explicitly 'a competitor's website' that changes the result set. It does not state whether domain should include a protocol or www prefix, leaving format ambiguity.

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 (a domain's backlink profile) and enumerates the returned metrics — linking sites, total links, authority 0-100 — plus the comparison mode. It does not explicitly distinguish itself from neighbors like check_links, check_site, or competitor_report, so an agent must infer the boundary rather than read 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?

Usage is implied: call it for backlink research, and add compare_with for a competitor gap analysis ('sites that link to the competitor but not to this site'). There is no explicit statement of when to prefer check_links or check_site, nor any prerequisite or cost guidance, so the routing decision is left 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=false, openWorldHint=true, and idempotentHint=false, but the description adds the reason: it consumes a credit ('Uses one read') and persists state ('saves the result in the user's Puley history'), which explains why a link-checking operation is not read-only. It also discloses that pages are fetched live at call time and enumerates every failure mode, so the agent knows what partial success looks like.

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 core action and the status taxonomy, then the optional parameter and use cases. It is dense with parentheticals and reads as a run-on, but every clause carries information (outcome states, limit, credit cost, history write) rather than 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?

There is no output schema, and the description compensates by defining the return vocabulary (Live/Dead/Site doesn't exist/Site error/Exists but blocks readers/Couldn't confirm) and what Live includes (real title, redirect target). Combined with the credit cost and 15-link cap, an agent has enough to call this correctly and interpret the response without further documentation.

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 0%, so the description must carry parameter meaning and largely does: 'claim' is defined as what the pages should say, with the matching behavior spelled out ('each live page is checked for its main words'), and 'links' is bounded ('Up to 15 links'). Minor gap: it doesn't say whether claim matching is exact, keyword-based, or how mismatches are reported in the result.

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

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

States a specific verb and resource ('Check whether links are real and live') and enumerates the exact outcome states (Live with title and redirect, Dead, Site doesn't exist, Site error, Exists but blocks readers, Couldn't confirm). This is clearly distinguishable from siblings like check_backlinks, check_site, read_site, or is_it_real, since it operates on a list of URLs rather than a site or claim.

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 contexts ('Suits sources, citations, store or product links and recommended websites') plus the decision prompt '(is the site still up?)'. It also states the hard limit 'Up to 15 links'. It stops short of naming explicit alternatives (e.g., use check_site for a whole domain, check_backlinks for link equity), so the agent must infer exclusion boundaries.

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 and non-idempotent, which would otherwise be puzzling for what looks like a read; the description resolves this by stating 'Uses one read and saves the result in the user's Puley history,' explaining the write side effect and the cost of each call. It also discloses the external open-world sources (public registry, Trustpilot) and sets the interpretive frame that the output is signaling rather than adjudication.

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 purpose and full list of returned facts lead, followed by the verdict caveat, the parameter format, and the side-effect note. The parenthetical source attributions are dense but each earns its place by telling the agent where the facts come from.

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 must describe returns, and it lists the Trustpilot fields and registry fact in enough detail for an agent to plan around. It does not describe behavior on domains with no Trustpilot profile or an unregistered site, nor the response shape, which leaves a modest gap for a single-input tool of this kind.

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 0%, so the description carries the full burden, and it does: 'website: a domain such as example.com, or a link' tells the agent both accepted input forms and gives a concrete format example. That is meaningfully more than the bare 'Website' string property 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?

The description names a concrete deliverable and enumerates its two data sources precisely: domain first-registration date from the public registry and a Trustpilot record (TrustScore, review count, 1-star share, summary, alerts, latest reviews). An agent knows exactly what comes back. It does not explicitly route away from overlapping siblings such as is_it_real, read_reviews, or company_brief, so it falls short of the top of the scale.

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?

'Facts to judge whether an online shop or company is trustworthy before buying' gives a clear situational trigger and set expectations with 'gives signals, not a verdict.' There is no explicit when-not guidance and no named alternative for cases where the agent wants reviews-only or company-level data, which keeps it below 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?

Adds substantial behavior beyond the annotations: one read is consumed, a detected change may send email, paused watches are not resumed, and watch-management permission is required. These details clarify side effects, cost, and authorization for a non-read-only operation.

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

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

Three short sentences with no wasted wording, and the core action is stated first. The permission and paused-watch exclusions follow naturally.

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?

Covers the important operational context: cost, side effects, permissions, and the paused-watch exclusion. It leaves the return value and watch_id lookup slightly implicit, but no output schema exists and the core invocation requirements are present.

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

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

The single watch_id parameter has no schema description, and the description only implies it must identify an active watch. It does not explain the integer format or how to obtain the ID, though the parameter name itself is fairly self-explanatory.

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: run a manual check of an active watch. It also distinguishes the action from resuming a paused watch, so an agent can separate it from get_watch, pause_watch, and resume_watch.

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?

Makes the triggering context clear: a requested manual check of an active watch. It includes an explicit exclusion for paused watches, though it does not name specific sibling alternatives such as resume_watch or get_watch.

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 and openWorldHint=true, and the description adds the reason: results are 'Saved in the user's Puley history', which explains the write side effect. It also discloses the shape of the return payload (categories with counts and quotes). It does not cover latency, cost, or failure behavior for unsupported links, but the key non-obvious side effect is disclosed.

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?

Purpose is front-loaded in the first clause, followed by compact parameter notes. Slightly awkward phrasing ('products they compare it with') but no wasted sentences and no repetition of the annotations.

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 spends words on the return structure — category names, counts, and quotes — which is exactly what an agent needs to decide whether the tool answers its question. Missing pieces are platform/link acceptance rules and any indication of how many comments must exist for categories to be meaningful.

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 0%, so the description must carry parameter meaning and it largely does: link is defined as 'the post', and limit is given a usable range of 20 to 200 comments. The default of 100 is left to the schema, and the format of 'link' (full URL vs. shortcode) remains ambiguous, which keeps it below a 5.

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

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

States a concrete verb+resource: it takes the comments under a TikTok/YouTube/Instagram post and sorts them into named categories (questions, complaints, compared products, loved features, requests) with counts and quotes. That is far more specific than the title 'Sort the comments'. It does not, however, distinguish itself from the sibling read_comments, so an agent must infer the difference between raw comment retrieval and this categorized analysis.

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: the output categories signal this is for analyzing audience sentiment/questions rather than fetching raw comments, which is the natural alternative (read_comments). There is no explicit 'use this when...' clause, no exclusion naming the sibling, and no note about which platforms/URL forms are accepted.

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, which could puzzle an agent for a research tool; the description resolves this by stating the result is 'Saved in the user's Puley history', explaining the write side effect. It also enumerates the content returned and implies open-web lookup via 'latest news', though it says nothing about latency, cost, or failure modes.

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 compact sentences: the first front-loads the use case and the payload, the second handles both parameters plus the side effect. Nothing is repeated from the title and there is no filler.

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

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

With only two parameters and no output schema, the description needs to preview return contents, and it does so field by field. The remaining gap is minor: no statement of expected depth or freshness of the news component.

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 0%, so the description carries the load and does: 'company' accepts a name or a domain (example acme.com), and 'country' selects the news edition. That is enough to format inputs correctly despite the bare schema, though it does not say what happens if country is omitted or invalid.

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 concrete resource and scope: a single-company brief containing what the company does, industry, headcount, website, LinkedIn and latest news. That is specific enough to separate it from competitor_report or account_report, although it never names a sibling 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?

The opening clause 'A company before a sales call' gives a clear usage context, so an agent knows this is pre-meeting research rather than a comparison or account-level report. It stops short of exclusions or pointing to alternatives for multi-company or existing-account needs.

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?

Beyond the annotations, the description discloses that each country consumes the user's read quota, that the comparison is persisted to their history, and that failed reads are flagged. It also explains the partial-result contract: comparable=false, a comparison_note explaining why, and no cheapest country. Only auth requirements and any rate-limit specifics are left unsaid.

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 core action and the cheapest-first ordering, and nearly every sentence carries information about behavior or output. The mid-sentence 'plan:' fragment is slightly awkward and interrupts the flow, but nothing 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 still conveys return shape: per-country local price converted to USD, stock, source of each read, cheapest-first ordering, a comparable flag, and a comparison_note on non-comparable results. For a three-parameter, non-idempotent, open-world tool, an agent has everything needed to call 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 coverage is 0%, so the description has to carry all three parameters, and it does: countries are two-letter codes like US/GB/JP, plan is the exact subscription plan or billing period and maps to a product variant, and link is the product URL whose format determines store resolution. Missing only concrete examples of accepted plan strings or a country-count limit.

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 concrete verb and resource: read the same product page from inside other countries and compare local price converted to USD, cheapest first, including stock and read source. That is far more specific than the title alone. It does not name the near sibling compare_stores or subscription_prices, so an agent still has to infer which tool to pick.

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?

Implied usage is clear (Apple and LEGO links resolve to each country's store), and the plan parameter's default behavior is spelled out. But there is no explicit when-to-use or when-not-to-use guidance versus compare_stores, subscription_prices, or plain read for a single country, and no stated prerequisites.

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?

Beyond the annotations it discloses cost ('uses one read per store that answers'), persistence ('saved in the user's Puley history'), and important result caveats: results follow each store's own ordering and may include accessories or other models, and shipping and tax are excluded. That is meaningful context the annotations (readOnlyHint false, openWorldHint true) do not convey. The phrase 'one read per store' sits slightly awkwardly against readOnlyHint=false, but it reads as a credit/consumption concept rather than a claim of read-only semantics, so it is not a real 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?

It is front-loaded and every clause carries information, but the body is a single dense paragraph of country and store enumerations that is hard to scan. Much of the length is unavoidable given no enums in the schema, yet the content would be far more usable as a list rather than a run-on sentence.

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, and the description fills that gap by naming the returned fields (name, price in local currency, was-price, rating, reviews, stock, units sold, link). Combined with the region-to-store mapping and the per_store cap, an agent has everything needed to call it correctly 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 0% and all four parameters are bare in the schema, so the description carries the full burden — and does: country is defined as two letters with default US plus an exhaustive per-country store mapping, stores is effectively enumerated with every accepted value and its region, per_store is bounded ('up to 12'), and query is implied by 'same product'. This is exactly the compensation the low coverage demands.

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 opening sentence states a specific verb and resource ('Search a country's big stores for the same product and list each store's results side by side, as a shopper there sees them') and enumerates the returned fields. It is clearly distinct from siblings like search_marketplace, best_sellers or resale_prices because the defining scope is cross-retailer price comparison within a country.

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

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

The description gives strong operational guidance: country drives which stores are queried, stores can 'narrow or add', per_store caps results, and specific use cases are called out (AliExpress for 'is it cheaper on AliExpress?', coles for unit prices, idealo as a price comparison). It stops short of naming an explicit alternative sibling or a 'do not use when' condition, so it is clear context without full 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?

The final sentence 'Saved in the user's Puley history' explains the otherwise puzzling readOnlyHint=false on what looks like a pure lookup, which is genuine value beyond the annotations. The 5-to-50 limit range is also disclosed, though nothing is said about what happens when a site has fewer results than the limit or about failure modes.

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 capability is stated first, then per-parameter notes in a compact labeled form. Despite being a dense single paragraph, every clause carries information and nothing 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 listing the fields returned for each kind (searches/month, cost per click, advertisers, position, clicks, page). Combined with the history-persistence note, an agent has enough to call it correctly; only error and empty-result behavior is 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 0%, so the description must carry the parameters, and it does: kind (paid vs organic with the returned metrics for each), website, country as a two-letter code, and limit as a 5-50 range. It omits the defaults (paid, 15, US) that the schema declares, which is a minor remaining gap.

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

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

The description names the resource precisely (the Google searches a competitor site pays for or ranks for) and splits it into two explicit modes, paid and organic, each with the fields returned. It does not distinguish itself from close siblings like keyword_research, competitor_report, or find_ads, so an agent cannot route between them 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?

Usage is only implied: the 'website: the competitor's site' phrasing signals this is a competitor-lookup tool, and the kind split hints at choosing paid vs organic. There is no explicit when-to-use, when-not-to-use, or named alternative such as keyword_research for one's own domain.

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 say it is not read-only, is open-world and not destructive; the description adds the details that matter: work happens asynchronously in the background, results are persisted to the person's Puley history, and an email is sent. Those are real side effects an agent must warn about before invoking. The re-call behaviour is disclosed too, though it sits slightly oddly against idempotentHint=false (a repeat call returning the existing run reads as deduplicated).

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 background/one-shot nature, then the parameter hint, then the polling rule. Every clause carries information. Minor awkwardness in the run-on phrasing of the first sentence slightly hurts scanability.

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

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

With no output schema, the description steps up by naming what the report contains and how the result reaches the user (history plus email). Combined with the polling note and the parameter hint, an agent has enough to invoke it correctly. Only the delivery timing and failure behaviour remain unspecified.

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

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

The single parameter has zero schema description coverage, so the description must carry the meaning — and it does, stating that 'competitor' accepts either a name or a website. That is exactly the disambiguation an agent needs to pass a valid value. It could go further on domain/format expectations, but the core gap is filled.

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 concrete verb chain and a concrete artifact: it reads a competitor's live ads and website, then writes what they push, how they sell and the gaps to use. That is far more specific than the name 'competitor_report' alone. It does not name the neighbouring tools an agent might confuse it with (company_brief, account_report, find_ads, read_site), so sibling differentiation is only implicit.

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 clearly frames the operating context — 'Runs once, in the background' — and tells the agent how to follow up: repeating the same request yields progress or the finished report. That is genuinely actionable polling guidance. It stops short of explicit exclusions or named alternatives for when a lighter tool would be better.

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?

With readOnlyHint=false and openWorldHint=true already declared, the description still adds real behavior: it is an asynchronous background job, results persist into the person's Puley history, an email is sent, and re-issuing the same request acts as a status check. It does not say how long a run takes or what happens on failure. There is mild tension with idempotentHint=false, since re-requesting sounds like it returns existing state rather than starting a new run, but it is not a direct 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?

The purpose and the async/persistence behavior are front-loaded, and no sentence is pure filler. The first sentence is long and strings five data sources together, which makes it slightly dense, but it earns its length by describing scope.

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 open-world, non-read-only background job with no output schema, the description covers the data sources, the deliverable, persistence, email delivery and polling. It still omits expected runtime, cost or quota implications, and any description of the returned result's shape beyond 'growth moves with evidence', and it ignores the second parameter.

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 0%, so the description must carry the load. It partially does, clarifying that 'brand' accepts either a name or a website, which is real added meaning. The 'country' parameter (default US) is never mentioned, leaving half the inputs undocumented in both schema and description.

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 concrete verb and deliverable: it reads a brand's live ads, creator videos, social posts, news and paid search, then writes copyable growth moves with evidence. That is far more specific than the sibling names (competitor_report, company_brief) suggest on their own, though it never explicitly contrasts itself with those nearby tools.

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

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

Usage context is implied through the audience framing ('the growth moves a smaller business could copy'), and there is a genuinely useful polling instruction ('The same request again returns its progress or the finished result'). However, there is no statement of when to prefer this over competitor_report or company_brief, and no guidance on preconditions such as a connected account.

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?

The annotations declare readOnlyHint=false on what looks like a pure lookup, and the description resolves that apparent oddity by stating results are 'Saved in the user's Puley history' — a genuine side effect the agent could not infer from the annotation alone. It also discloses the 10-creator cap and that it reaches external platforms (matching openWorldHint=true). It stops short of noting idempotency behaviour or what happens on invalid handles.

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?

It is short and the batch limit is front-loaded, but it is written as a run-on fragment with no clear sentence boundaries, and the metric list ('typical as a share of followers') is compressed to the point of ambiguity. Information density is high, yet the phrasing costs readability.

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 only two parameters, no output schema, and annotations covering the safety profile, the essential information is present: inputs, the metrics returned, the batch cap, and the persistence side effect. Missing pieces — return format, behaviour beyond the 10-creator limit, error handling — are minor for a tool this simple.

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 0%, so the description carries the full burden and largely does: 'creators' is defined as comma-separated usernames, and 'platform' is constrained to instagram, tiktok or youtube — a constraint the schema does not encode as an enum. It omits accepted handle formats (with or without '@', URLs) and case sensitivity, leaving a small gap.

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

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

The description names the resource (creators) and enumerates the exact payload returned: followers, typical views/likes on recent posts, typicals as a share of followers, engagement, and recent breakout posts. That is far more than the vague verb 'check' conveys on its own. It does not differentiate itself from near neighbours such as viral_outliers, comment_insights, or find_channels, 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?

'Up to 10 creators side by side before paying them' implies a vetting/decision-support use case and states a hard batch limit of 10. However, it never says when to prefer this over viral_outliers or find_channels, nor what to do when more than 10 creators must be evaluated. Usage is implied rather than prescribed.

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?

With readOnlyHint=false and openWorldHint=true already declared, the description adds the crucial reassurance that 'Puley sends nothing to the businesses' — the drafting is for human review, not automated outreach — and that results persist in history and are emailed. It also discloses the async pattern and the repeat-call polling behavior, which annotations alone would not convey. There is a mild tension with idempotentHint=false (a repeated identical request is described as returning existing progress rather than starting a new job), but it is a nuance about job reuse rather than a claim that the tool is read-only.

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 first sentence front-loads the whole flow (list, then draft, for the person to review), and the delivery facts ('saved in history', 'emailed') and polling rule follow in a sensible order. It is dense and slightly run-on, with the parameter glosses appended inline rather than separated, but almost every clause carries information an agent needs.

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 3-parameter background job with no output schema, the description covers what it produces (a list with contact details plus drafted messages), where results land (history and email), and how to retrieve them (re-issue the request). What is missing is scope or cost expectations — rough runtime, breadth limits on the business list, or credit implications — which an agent would want before firing an open-world job.

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 0%, so the description carries the full burden, and it does: business is glossed as 'the kind of business (dentists)', place as 'a city or area with its country', and offer as 'what the person sells'. That resolves the two genuinely ambiguous inputs and the formatting expectation for place. It still leaves offer's default empty-string behavior and length/format expectations unstated.

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 concrete verb chain and resource: list businesses of a kind in a place with phone/email/website, then draft a short first message per business from the user's offer. That is far more specific than the title 'Customers and first messages' and an agent can picture the output. It does not, however, distinguish itself from close siblings such as find_leads or find_contact, which an agent would plausibly weigh against 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?

Usage is only implied: 'Runs once, in the background' plus 'The same request again returns its progress or the finished list' tells the agent how to poll, which is real guidance for an async job. But there is no explicit when-to-use or when-not-to-use statement, and no pointer to an alternative tool for a narrower lookup (e.g. a single contact or plain lead search).

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 destructiveHint=true and idempotentHint=true, yet the description adds real substance beyond them: exactly what is destroyed (the check history), what survives ('Earlier alerts remain'), how invalid/foreign IDs are handled, and the permission needed. That is precisely the data-loss and error-behavior context an agent needs before calling a destructive tool.

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 short sentences, front-loaded with the destructive nature and the scope of deletion, then the retention note, the error case, and the permission requirement. Nothing is repeated from the annotations and no sentence 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?

For a single-parameter destructive tool with no output schema, the description covers consequences, retention, error behavior and authorization, which is close to sufficient. It stops short of routing the agent to list_watches for ID discovery or to pause_watch for the reversible case, which is the main remaining 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 0%, so watch_id is undocumented in the schema. The description partially compensates by constraining it to an ID that must belong to the user's watches (and implying refusal otherwise), but it never says how to obtain a valid ID, nor adds type or format guidance beyond the integer type 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 ('Permanently remove one watch') plus the scope of removal ('its check history'), which separates it cleanly from get_watch, list_watches, pause_watch and resume_watch in the sibling list. An agent can tell exactly what this does 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?

Usage is only implied: the word 'Permanently' hints that pause_watch is the reversible alternative, but that sibling is never named and there is no explicit when-not-to-use guidance. The refusal rule for foreign IDs is the closest thing to a precondition, and the permission requirement covers the access side.

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?

The annotations declare readOnlyHint=false on what looks like a pure lookup, and the description resolves that apparent oddity by explaining it 'Uses one read and saves the result in the user's Puley history' — a side effect the agent would otherwise not anticipate. It also discloses the not-carried case ('Says so when Cost Plus doesn't sell it'). It does not mention auth, rate limits, or freshness of the published price list.

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 core answer (what the drug costs without insurance, and the source), then the returned fields, then the caveats. The long enumeration sentence is dense but each clause maps to a distinct output field. Slightly tighter punctuation and a shorter history note would make it cleaner, but 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?

No output schema exists, and the description fully carries the return contract: per strength and form, 30/60/90-pill pricing including the pharmacy fee, shipping-inclusive total, and in-stock status. Combined with the source, the miss behavior, and the history-write note, an agent has everything needed to call this correctly and interpret the result.

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?

With 0% schema description coverage and only bare titles, the description compensates by defining both parameters semantically: drug accepts generic or brand names with concrete examples (atorvastatin, Lipitor), and strength is shown as '10mg'. It leaves one gap: strength defaults to empty and the description never says what omitting it does (presumably return all strengths).

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 — the out-of-pocket cost of a prescription drug at Cost Plus Drugs, sourced from its published price list — and enumerates what is returned (strength/form, 30/60/90-pill prices with pharmacy fee, total with shipping, stock status). This clearly separates it from the price siblings (gas_prices, ticket_prices, subscription_prices, resale_prices) without needing to name them.

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 scope phrase 'without insurance at Cost Plus Drugs' tells the agent when this applies and implicitly when it does not (insurance pricing, other pharmacies), and 'Says so when Cost Plus doesn't sell it' sets expectations for misses. 'Prices only, not medical advice' is a useful exclusion. It stops short of explicitly routing to any alternative for non-Cost-Plus pricing queries.

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=false, openWorldHint=true, and destructiveHint=false. The description adds useful behavioral context by stating results are 'Saved in the user's Puley history' and by listing the returned review fields, but it does not explain pagination, rate limits, or how the limit parameter affects retrieval.

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 compact and front-loaded, using two sentences with no filler. The field list is somewhat dense but still purposeful.

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 simple two-parameter tool with no output schema, the description covers purpose, returned fields, the accepted company identifier, and the history-saving side effect. The main gap is that limit behavior is not described.

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 0%, so the description must carry parameter meaning. It does clarify that company can be a name or a Glassdoor reviews link, which is valuable, but it does not document the limit parameter or its default of 15.

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: it returns a company's newest Glassdoor reviews, including rating, pros, cons, role, staff status, and date. It is clear enough to distinguish from tools like salaries or company_brief, but it does not explicitly name or contrast with close siblings such as read_reviews.

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 or when-not-to-use guidance, and no alternative tool is named. The only usage cue is implicit: supply a company name or Glassdoor reviews link to get newest reviews.

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?

Beyond the annotations, it discloses quota mechanics (one read allowance per nonempty request), result bounds (account allowance, up to 20 ads), persistence to the user's Puley history, and a false-negative caveat that an access error or empty sample is not proof of no ads. This is genuinely additive context not present in readOnlyHint/openWorldHint. It does not state authentication or per-country filtering behaviour, so it stops short of 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?

The content is dense but every sentence contributes: platform routing, identity caveat, return contents, false-negative warning, quota/bounds, and the no-mutation statement. The only structural weakness is the mid-sentence line break and a slightly run-on flow that could be split into clearer clauses.

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 summarises what comes back (ad links, copy, advertiser IDs, destination links) and covers quota, bounds, and the read-only-in-spirit caveat. It remains incomplete for a 6-parameter open-world tool because limit, status, country, and platform values are never described.

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 0%, so the description must carry the burden, and it explains only 'query' and 'advertiser' semantically, plus an implicit platform split. It says nothing about 'limit', 'status', 'country' (including the 'ALL' default), or the accepted 'platform' values, leaving half the parameters undocumented anywhere.

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

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

The description opens with a specific verb and resource — searching the Meta Ad Library (Facebook/Instagram) or Google Ads Transparency — and names the two distinct advertiser-targeting modes. That is enough to separate it from neighbouring tools such as search_posts, google_results, or product_ad_pack 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?

It gives concrete routing guidance per platform: for Meta, query searches keywords while advertiser targets a Page URL/id/name; for Google, the advertiser name, website or ID is used. It also cautions that a website keyword is not a verified Page identity, which steers correct input choice. What it lacks is explicit when-to-use/when-not guidance relative to siblings or named alternatives.

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?

The most valuable disclosure is 'Uses one read and saves the result in the user's Puley history,' which explains why readOnlyHint is false on what looks like a search — that is real context beyond the annotations. It also discloses the exact fields each car returns. It stops short of stating result limits, pagination, or empty-result behavior, so a 3 rather than higher.

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 key scoping facts ('cheapest first', country default) are front-loaded, and nearly every clause carries distinct information. However, the core content is delivered as one enormous sentence with deeply nested parentheticals, making it hard to scan and easy to mis-parse despite its density being roughly justified by eight marketplaces.

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 still specifies the returned fields (price, year, mileage, town, fuel, gearbox, power/body, seller, links) and notes the single-read cost plus history persistence. It omits how many results come back and what happens when nothing matches, which leaves a modest gap for a query tool spanning eight sources.

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?

With 0% schema description coverage across 7 parameters, the description carries the full burden and does: make/model examples, max_price in the local currency, min_year, and the crucial clarification that max_km is interpreted as miles in the US and UK. Province is given per-market meaning — a city in India/Brazil, a region in Canada/South Africa, a postcode in the UK — which the schema cannot convey at all.

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 and resource — 'Cars for sale, cheapest first' — then enumerates the eight marketplaces and their country codes, so an agent knows exactly what this surfaces. It never names the overlapping siblings (search_classifieds, search_marketplace, resale_prices), so differentiation from those relies on inference from the car-specific scope.

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 operational routing: country ZA is the default, each country maps to a distinct marketplace, and province/town semantics differ per market. What it lacks is any statement of when NOT to use it or which sibling to reach for instead, so the guidance is contextual but not exclusive.

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?

The description adds real context beyond the annotations: it costs one read (explaining readOnlyHint=false) and persists the result list into the user's Puley history, a durable side effect the annotations only hint at. It does not cover failure modes or auth requirements, but the credit-cost and side-effect disclosure is the important part.

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?

Purpose is front-loaded in the first clause, then return fields, then cost/limit/history notes. It is dense and slightly run-on, but every clause carries information; nothing 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?

For a two-parameter tool with no output schema, the description covers return shape, cost, and persistence, which is most of what an agent needs. It stops short on edge behavior such as what happens when limit exceeds 20 or whether results are deduplicated.

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?

With 0% schema description coverage, the description carries the load and does address both parameters: 'topic' is defined as the subject of the search, and 'limit' gains the ceiling 'up to 20' that the bare schema lacks. The default of 10 and any topic-format guidance remain undocumented, keeping it short of a 5.

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

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

States a specific verb and resource ('Find YouTube channels about a topic') and immediately enumerates the returned fields (name, handle, subscribers, verified badge, description, link), which cleanly separates it from siblings like find_videos or google_results.

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?

Offers one implied scenario, 'Useful for finding creators in a niche,' but gives no when-not guidance and never names an alternative tool (e.g., find_videos or google_results) for adjacent intents, leaving the agent to infer boundaries from the name alone.

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

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

With readOnlyHint=false and openWorldHint=true, the description supplies the missing context: results are 'checked,' contact details are gated behind an account-owner setting in Puley, and the tool reports that state rather than failing silently. It also explains the non-read-only annotation by noting results are 'Saved in the user's Puley history' — a genuinely useful disclosure that annotations alone would not convey. It stops short of describing how verification is performed or what a partially matched result looks like.

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 three sentences each carry information, and the return value is front-loaded. But the opening is a noun phrase rather than a verb, the colon after 'checked' reads awkwardly, and 'otherwise this says so' is vague filler that could have been stated concretely as the returned message.

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 correctly spends effort on the return: a person, their work email, a verification claim, and the fallback message when contacts are disabled. For a three-parameter lookup this covers what an agent needs, with only the multi-match case and result shape left unstated.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: 'company (name or website)' clarifies the accepted format, 'role (head of marketing)' gives a concrete example of the expected phrasing, and 'the person's name' is identified as an alternative targeting path. What it omits is the interaction rule between name and role and what happens when neither is supplied.

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 outcome: 'The person to contact at a company and their work email, checked,' which tells an agent this returns a named contact plus a verified email, not a company profile or a lead list. It does not explicitly distinguish itself from near-neighbours like find_leads or company_brief, so the boundary with siblings is left implicit.

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 the input recipe ('give the company ... and the role ... or the person's name'), which implies when the tool applies. However it never states when to prefer find_leads or company_brief instead, nor whether role and name are mutually exclusive or can be combined, leaving real selection ambiguity.

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?

The description earns its keep by explaining the surprising annotation: readOnlyHint=false makes sense because it 'Uses one read and saves the result in the user's Puley history.' It also caps expectations with 'Up to 20 events' and previews the return payload. Missing only things like failure modes or what happens when the read budget is exhausted.

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 in the first clause and every subsequent clause maps to a parameter or an output field, so density is justified. It reads as one long run-on paragraph rather than structured lines, which costs a little scannability.

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 6-parameter, no-output-schema tool this covers the essentials: what is searched, what comes back, the result cap, and the side effect on the user's history. Only free_only is left entirely undefined, which is the one real hole.

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 0%, so the description must carry the load, and it largely does: it defines place with concrete examples ('Austin, TX', 'London', or 'online'), country as a two-letter code with examples, query with kind examples, and when with a full enumerated value list plus a date-range syntax. The gaps are limit (only hinted at via 'Up to 20 events') and free_only, which is never mentioned.

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 concrete verb+resource framing ('What's on near a place, from Eventbrite') and enumerates the exact content types covered (concerts, comedy, classes, markets, festivals, meetups). This clearly separates it from siblings like find_places, showtimes, ticket_prices and where_to_watch without needing 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?

The 'what's on near a place' framing plus the query guidance ('empty for everything') implies when to reach for it, but there is no explicit when-not guidance and no sibling is named as an alternative. An agent can infer usage but is not routed.

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?

The annotations declare readOnlyHint=false and openWorldHint=true, and the description explains why: 'Uses two reads and saves the result in the user's Puley history', which accounts for the non-read-only profile and the double cost. It also conveys data recency ('live', 'right now'), but does not cover rate limits, quotas, or failure 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?

Content is front-loaded on what is returned, then parameter semantics, then the side effect. It is dense but each clause adds information; the colon-separated parameter notes are slightly run-on, which costs a point.

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 adequately enumerates the fields an agent would receive and notes sorting and price-level assessment. The only substantive gap for a 6-parameter tool is the undocumented 'nonstop' flag and no indication of result limits.

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 0%, so the description carries the full burden and mostly does: it defines origin/destination as a city or airport code, gives the YYYY-MM-DD format for depart/return_date, explains the one-way omission, and gives currency examples. The 'nonstop' boolean is the one parameter left undefined.

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 (live fares from Google Flights for a route and dates) plus the exact returned fields: price, airline, stops, times, duration, layovers, sorting and Google's price-level verdict. This clearly separates it from siblings like flight_status (status of a specific flight) or find_cars/find_stays (other travel 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?

Usage is implied through the parameter-level guidance ('no return_date for one way'), which tells the agent how to handle one-way searches. However, it never states when to prefer this over a sibling such as flight_status, ticket_prices or find_stays, nor are any exclusions or prerequisites given.

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?

Adds real context beyond the annotations: it explains the readOnlyHint=false by disclosing that the call 'uses one read and saves the result in the user's Puley history', and it flags latency for several portals (Domain about 30-50 s, Funda about a minute, SeLoger and Immobiliare slower). It also describes the listing payload (price, beds, baths, size, address, listed/reduced dates, Zestimate on Zillow) which is valuable given there is no output schema. Error behavior and failure modes are not 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?

The core facts are front-loaded and nearly every clause carries routing information an agent needs, but the sixteen portal entries are delivered as one dense semicolon-separated block rather than a scannable list or table. The repeated 'country XX' pattern and per-portal examples make it long and hard to parse in a single pass.

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 five-parameter open-world aggregation tool with no output schema and no annotation-level detail, this is close to complete: input formats, currency handling, return fields, latency warnings, and the history side effect are all stated. The gaps are min_beds semantics and any mention of failure or empty-result 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 0%, so the description must carry the parameter burden. It covers place in depth (per-country formats and examples), country via the per-portal ISO codes, max_price ('in the local currency, 0 for any'), and mode ('buy or rent'). It never explains min_beds, and only hints at it obliquely ('rooms, not bedrooms' for immowelt), leaving one of five parameters undefined.

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?

A specific verb+resource ('Homes for sale or rent, newest first') with an exhaustive enumeration of the source portals per country, so an agent knows exactly what corpus is searched. It never names a sibling (find_stays, find_cars, search_classifieds, search_marketplace) to draw the boundary, so sibling differentiation is left implicit 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?

Strong conditional guidance: it tells the agent which portal applies to which country, what location format each expects (e.g. 'Bondi, NSW' for Domain, 'Annex, Toronto' for Zolo, 'SW4' for Rightmove), and routes Quebec places to Centris. It stops short of stating exclusions — nothing says when to prefer find_stays or search_classifieds instead — so it is clear context without explicit negative 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 mark this as openWorldHint=true, destructiveHint=false and readOnlyHint=false, and the description explains the surprising part of that profile: 'Uses one read and saves the result in the user's Puley history', which clarifies why a search is not read-only and implies a cost/credit model. That is genuine added context beyond the annotations, though it stops short of stating failure modes, rate limits, or pagination behavior.

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

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

The return fields and data sources are front-loaded before the parameter list, and each sentence carries information. The parameter run-on is dense and slightly telegraphic ('days: any, 1, 3, 7 or 14'), 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?

With seven parameters, no output schema, and zero schema descriptions, the description supplies the return field list, the per-country board mapping, allowed parameter values, and the side effect of history-saving. What remains thin is how location interacts with country and what the query string is matched against.

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 0%, so the description carries the full burden and mostly delivers: it gives allowed values for days (any, 1, 3, 7, 14), sort (relevance or date), limit range (5 to 50), the format of country (two-letter code) and the special board value 'upwork' with its distinct return fields. Only query and location are left undefined, which keeps it below a 5.

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

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

Opens with a specific verb and resource ('Jobs for a search and place') and enumerates the returned fields (title, company, location, pay, job type, posted date, snippet, links), which makes the output shape unambiguous. It does not explicitly differentiate itself from adjacent find_* siblings such as find_leads or search_classifieds, but the job-board framing is distinctive enough to route correctly.

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 through the country/board coverage map and the in-tool alternative 'board: upwork for freelance work instead', which is a useful routing rule. However there is no explicit when-to-use or when-not guidance against sibling tools, and no stated prerequisites for the country/board combination.

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 non-read-only, open-world, non-idempotent, non-destructive behavior, and the description adds genuinely new context beyond that: latency expectations (~1 minute for 60), side effects (results persisted in the user's Puley history with a spreadsheet download link), and provenance (contact details are each business's own published ones). It does not cover failure modes or what happens with zero results, but the added context is meaningful.

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 sentence is long and clause-heavy, cramming the return shape, provenance, and table format into one breath before the parameters are addressed. Later sentences become telegraphic fragments ('what: the kind of business', 'count: up to 60 a call'), which are efficient but inconsistent in register with the opener.

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 describes the result shape (one table of businesses with named fields) and where it lands (Puley history plus spreadsheet link). For a 4-parameter, open-world scraping tool it is nearly complete; only edge behavior such as empty results or what happens beyond 60 leads is 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 0%, so the description carries the full burden and does so: 'what' is explained with concrete examples (dentists, solar installers, wedding venues), 'where' specifies a city or area with its country, 'count' gives the ceiling (60) and timing, and 'min_rating' enumerates the accepted values (0, 3, 3.5, 4, 4.5). This is information the schema lacks entirely.

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 concrete resource and enumerates what each record contains (rating, reviews, phone, business email, WhatsApp, website, social profiles), which is far more specific than the bare name. It stops short of explicitly distinguishing itself from near-siblings like find_places or maps_rank, which also deal with places/business data.

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 framing ('Local businesses to sell to, in one call'), which signals a lead-generation intent, and the parameter notes give practical constraints (up to 60 per call, ~1 minute). However there is no explicit when-to-use / when-not-to-use guidance and no named alternative among the many find_* siblings.

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

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

The annotations declare readOnlyHint=false and openWorldHint=true, and the description usefully explains why: it 'saves the result in the user's Puley history', which reconciles a read-looking tool with a non-read-only hint. It also discloses a cost signal ('uses one read'), which is exactly the kind of quota context annotations cannot carry; it stops short of saying whether history entries can be removed or whether repeated calls are deduplicated.

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 returns before dropping into compact per-parameter notes; nearly every clause carries information. The telegraphic colon-list style is efficient but slightly dense, and the return-field enumeration overlaps with what an output schema would normally cover.

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 four parameters, no output schema and open-world scope, the description covers return shape, ordering, edition semantics, all enum-like values and a side-effect/cost note. The remaining gaps — defaults, history retention, and how results differ from google_results — are modest for a tool of this complexity.

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 0%, so the description carries the full burden and largely does: it gives country as two-letter codes with examples (US, GB, ZA, AU, IN), enumerates the legal period values (any, hour, day, week, month), and caps limit at 30. It omits the defaults (limit 12, period 'any', country 'US') and leaves query undescribed beyond 'about something', which keeps it from a 5.

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

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

The description names a specific resource and scope: latest news for a query, newest-first ordering, rendered as a country edition, with the exact fields returned listed. It is clearly distinct from siblings like find_videos or search_posts by virtue of the 'news' framing, but it never names a near-neighbour such as google_results or search_trends to say which to prefer.

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

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

Usage is only implied by the resource name — an agent can infer 'use this to look up current news' but there is no explicit when-to-use, when-not, or alternative-naming guidance. No prerequisites (auth, plan, quota tier) are stated.

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?

The description usefully explains the surprising annotation combination: readOnlyHint=false and non-idempotent are accounted for by 'uses one read and saves the result in the user's Puley history', which the agent could not infer from the annotations alone. It also discloses the limit ceiling of 25. It says nothing about cost, rate limits, or what happens on subsequent identical calls despite idempotentHint=false.

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 core statement and free of filler; the returned-field enumeration earns its space because there is no output schema. The sentence is long and dense, but nothing 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, describing the returned fields and the linked-sites summary is exactly the needed compensation, and the history side effect is disclosed. Gaps remain around query formatting and whether a follow-up call (e.g. more_results) is needed to go past 25.

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 0%, so the description must carry both parameters. It adds real meaning for limit ('up to 25', matching the schema default but revealing the cap) and implies query is a topic/search string. It gives no query syntax guidance (keywords vs phrases, language, locale), leaving the main required parameter underspecified.

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 ('Pinterest's top pins') plus scope ('for a search, as Pinterest ranks them') and enumerates what each result carries. It is readily distinguishable from sibling search tools such as find_videos, search_posts, and google_results.

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 frames when this applies ('good for ideas and inspiration... and for seeing which sites and creators rank on Pinterest for a topic'), which steers the agent well. It does not name an alternative tool or state when not to use it, so it falls short of the top band.

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?

Adds substantial behavior beyond the annotations: a credit/cost model ('uses one read per 20 places'), a persistent side effect ('saved in the user's Puley history'), and a hard output cap ('up to 60'). The history-saving disclosure is especially valuable because it explains why readOnlyHint is false despite this being a lookup, so the agent will not assume the call is free of side effects.

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 and front-loaded: the resource and return fields come first, then cost/limit, then scope exclusions. It is a single run-on block rather than structured lines, but no sentence is filler and each clause carries operational 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?

For a three-parameter tool with no output schema, the description supplies the return shape, the cost model, the result cap, the persistence side effect, and the scope boundary. An agent has everything needed to decide whether to call it and what to expect back.

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?

With 0% schema description coverage the description has to carry the parameter burden, and it mostly does: query is illustrated with a concrete 'coffee shops' in 'Austin, TX' shape, and limit is bounded ('up to 60') against the schema's bare default of 20. The location parameter is only implied by the example format rather than described directly, leaving a small gap.

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 ('List the businesses or places Google Maps shows for a search') and enumerates the returned fields (name, category, rating, review count, address, phone, website, open-now, Maps link). It also draws a hard boundary against the nearest sibling category with 'Business listings only; never people', separating it from find_leads and find_contact.

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 when-not guidance: 'Business listings only; never people' and 'Meant for research, not bulk marketing messages', which steers the agent away from lead-gen/outreach use. It stops short of naming a specific alternative tool to use instead for people or bulk messaging, so the routing is implied 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 declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false, and the description supplies the missing 'why': it 'uses one read and saves the result in the user's Puley history,' which explains the non-read-only flag and discloses a persistent side effect. It also discloses the silent default behavior for omitted dates ('assumed two weeks out for two nights and flagged'), which is exactly the kind of context 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?

The purpose and return shape are front-loaded in the first clause, followed by compact per-parameter notes; nearly every phrase carries information. It is a dense run-on sentence rather than cleanly structured lines, which costs a little readability but not content.

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 8-parameter, no-output-schema, open-world search tool, the description covers result contents, defaults, filtering conventions, and the history-write side effect, so an agent could call it correctly without opening the schema. Remaining gaps are minor: guest count semantics, result volume/pagination, and any failure behavior when a site returns nothing.

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?

With schema description coverage at 0% across 8 parameters, the description carries the burden and largely meets it: it documents checkin/checkout format and default behavior, max_per_night units and the 0-means-any convention, sort values (price or rating), and sites values (airbnb, booking, default both). The gaps are adults (default 2) and currency (only indirectly referenced via 'in the currency'), so coverage is strong but not complete.

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

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

The description names a specific verb and resource ('places to stay on Airbnb and Booking.com ... side by side') and enumerates the returned attributes (price for the dates and a night, rating, area, room, free cancellation, links). It does not, however, distinguish itself from near-neighbors in the sibling list such as find_homes or find_places, leaving an agent to guess which lodging tool to pick.

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: an agent can infer this is the tool for accommodation searches with a place and dates. There is no explicit when-to-use/when-not framing and no routing guidance against find_homes, find_places, or find_cars, so the choice among travel-search siblings is left 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 safety (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does, disclosing catalogue size (~4,000 tools), exactly what each result record contains (id, description, inputs, approximate read cost), and that the search itself consumes no reads. Only the result-set behavior (ranking, pagination, what happens on zero matches) is left unstated.

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 action and cost hint are front-loaded in the first clause, and the closing sentence about result contents and zero read cost earns its place. The long middle enumeration of data categories is defensible for query matching but is a laundry list that could be tightened.

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 compensates by describing the shape of each returned record and the read-cost field. Combined with the free-search disclosure, an agent has enough to call it correctly, though the missing `limit` semantics and the unstated hand-off to use_tool leave small 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 0%, so the description must carry parameter meaning. It clarifies that `job` is a natural-language job-to-be-done rather than a keyword or tool name, which is genuinely useful. But the `limit` parameter (default 8) is never mentioned, leaving half the parameters undocumented in both schema and description.

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 a catalogue of about 4,000 data tools by the job to be done" — which unambiguously identifies this as a meta/discovery tool, distinct from every sibling that performs the actual data work (keyword_research, find_news, check_backlinks, etc.). The category enumeration further pins down the scope of what is searchable.

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?

Clear context is given: search by job description, and "Searching uses no reads" tells the agent this is a free pre-step. However, it never names the natural follow-on (use_tool) or states when NOT to search — an agent must infer the two-step discover-then-invoke flow from the phrase "Each tool found comes with its id."

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 and openWorldHint=true; the description supplies the reason by disclosing "Uses one read and saves the list in the user's Puley history", which explains the cost and the side effect of a saved history entry. It also previews the returned fields per platform in the absence of an output schema. It does not cover failure modes or rate limits.

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 core purpose, then per-platform return fields, then per-parameter constraints; almost no filler. The prose is a single run-on block with line-wrapped parentheticals, so the constraint list takes a second pass to parse.

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 5-parameter open-world search with no output schema, the description covers platform behavior, result shapes, sort/filter scope and the credit cost, which is close to everything an agent needs to call it correctly. Pagination and error behavior are the only notable omissions.

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 0% and no enums are declared, so the description carries the full burden and largely discharges it: it gives the accepted values for sort, uploaded and platform, scopes sort and uploaded to YouTube only, and caps limit at 20. Defaults are left to the schema, but every parameter gains meaning the raw schema lacks.

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 videos about a topic") and immediately enumerates what each platform variant returns, so the agent knows this is a social-video search rather than a web search. It does not name a sibling to contrast with (e.g. google_results, find_news, watch_video), so the differentiation is implicit rather than explicit.

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 makes the platform choice clear (youtube default, tiktok hashtag, instagram reels under a hashtag) and lists the sort/uploaded options, which implies when to pick each. However, it never says when to prefer this over sibling tools like google_results or find_channels, nor does it give 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?

The description adds real context beyond the annotations: it discloses the cost ('Uses one read') and a persistence side effect ('saves the result in the user's Puley history'), which usefully explains why readOnlyHint is false for a lookup-style tool. It also attributes the upstream data source (FlightAware), implying open-world, externally-dependent results. It stops short of covering failure modes or staleness of the live data.

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 answer content is front-loaded in the first clause and the enumerated status list is efficient. The single sentence is dense and slightly run-on with its long series of returned fields, 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?

For a one-parameter tool with no output schema, the description covers the return value in detail (status category, local times, gates, terminals, aircraft, other days), notes the cost and the history write, and explains the input format by example. What remains — date anchoring and unknown-flight behavior — is minor relative to a tool this simple.

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 0%, so the description must carry the parameter's meaning, and it does add value by naming it ('flight: the flight number') and giving varied format examples with and without spaces (BA117, UA 1, DL1). It does not clarify whether the lookup is anchored to today's date or how the 'same flight on other days' return is keyed, leaving a genuine ambiguity given the single free-text parameter.

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 precise resource and scope: real-time status of one flight from FlightAware, enumerated as on time/delayed/in the air/landed/cancelled/diverted, plus the specific data returned (local departure and arrival times, gates, terminals, aircraft, same flight on other days). This is clearly distinguishable from the search-oriented sibling find_flights, which locates flights rather than reporting one flight's current state.

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 'Where a flight is right now' — the agent can infer this is for looking up a known flight number, not for discovering flights. However, there is no explicit when-to-use versus find_flights, no note about when the answer would be ambiguous (e.g. multiple days or unknown flight numbers), and no 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?

The description explains the otherwise puzzling readOnlyHint=false annotation by disclosing the side effect: the result is saved to the user's Puley history. It also adds cost/quota context ('uses one read'), the upstream source, result ordering, and freshness metadata (how long ago each price was reported) that 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?

Content is front-loaded with purpose, then output shape, then parameters, with no filler sentences. It reads as one dense run-on paragraph, which slightly hurts scannability but costs no wasted words.

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

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

For a two-parameter, no-output-schema lookup tool, it covers source, region, return fields, ordering, quota cost, and the history side effect. Minor gaps remain, such as whether Canadian prices are per gallon or per litre and what error behavior looks like for unsupported locations.

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 0%, so the description must carry the parameters, and it does: it gives three concrete place formats for the required 'place' argument and enumerates the fuel options (regular, midgrade, premium, diesel) that the schema leaves as a bare string with only a default. This is meaning the schema does not provide.

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 ('the cheapest gas near a ... ZIP or postal code or a town'), names the data source (GasBuddy), and enumerates the payload (price per gallon, address, report age, cheapest first, plus state and country averages). It is unambiguously distinct from price siblings such as drug_prices, resale_prices, or subscription_prices.

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?

Input examples ('78701', 'Austin, TX', 'M5V 2T6') imply the intended calling context and the geographic scope is US/Canada only, which is implicit guidance. However, there is no explicit statement of when to prefer this tool over a sibling lookup or what happens outside those regions, so usage is inferred rather than stated.

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?

Beyond the annotations, the description discloses the important behavior: the work runs once in the background, has persistent side effects (writes to Puley history and sends an email), and is polled by repeating the identical request. That is meaningful disclosure for an async job. Gaps remain around expected duration, poll cadence, failure modes, and there is a mild tension with idempotentHint=false, since repeated identical calls are described as returning existing progress rather than launching new work.

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 pipeline sentence is long but earns most of its length, and the polling note at the end is high value. However, the parameter glosses are jammed into the prose mid-paragraph as sentence fragments ('what: what is sold, and where. business: its name or website.'), which reads as an afterthought and hurts scannability.

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 async tool with no output schema, the description does the necessary work: it explains that the result is a plan saved to history and emailed, and that intermediate calls return progress. The remaining shortfall is the undocumented 'country' input and the absence of any sense of how long the background run takes.

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 0%, so the description must carry parameter meaning, and it only partly does. 'what: what is sold, and where' is genuinely ambiguous about whether location belongs in 'what' or in the separate 'country' parameter, and 'country' (default 'US') is never mentioned at all despite materially changing which sites get quoted.

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 concrete outcome and the mechanism behind it: query ChatGPT and Gemini for recommendations, find the sites the answers quote, read the user's site, and write a plan to get named. That is far more specific than the passive name 'get_recommended_by_ai' suggests. It never distinguishes itself from the confusingly similar sibling 'ai_recommends', which an agent would plausibly confuse with this tool.

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

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

Usage context is implied rather than stated: the tool is for someone who sells something and wants to be named in AI answers, and the final sentence tells the agent how to poll ('The same request again returns its progress or the finished plan'). There are no explicit when-not conditions and no routing away from siblings such as 'ai_recommends' or 'company_brief'.

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 safety (readOnlyHint, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: it discloses the returned data surface and pre-empts the main confusion by stating the call does not execute a check. It stops short of saying what happens for an unknown or non-owned watch_id.

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

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

Two sentences, zero filler, returned fields front-loaded and the negative constraint placed last where it functions as a boundary. Every clause earns 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 one parameter and no output schema, the description compensates well by naming the response fields. The remaining gap is provenance of the watch_id and error behavior, minor for a read-only single-record fetch.

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

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

The single watch_id parameter carries 0% schema description coverage, and the description only clarifies that it is 'one of the user's watch IDs' — useful ownership scoping but no hint on how the ID is obtained or what an invalid value yields.

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 ('Read ... watch') and enumerates exactly what comes back: recent check history, last success, retry schedule, delivery state. The closing clause 'Does not run a check' carves it apart from check_watch_now, though it never names that sibling 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?

The 'Does not run a check' line implies usage (inspect state rather than trigger execution), but there is no positive guidance such as 'use list_watches first to obtain a watch_id' and no exclusions against pause_watch/resume_watch/delete_watch, which all take the same identifier.

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 and openWorldHint=true, and the description usefully explains why: results are 'Saved in the user's Puley history,' disclosing the write-like side effect the annotations hint at. It also discloses that results are country-localized and ordered, which is behavior beyond the structured fields, though rate limits or freshness/caching behavior remain unstated.

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 capability and return fields are front-loaded in the first clause, and every subsequent fragment adds a parameter or scope detail. The sentence is somewhat run-on, but there is no filler or redundant restatement of the title.

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

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

With no output schema, the description does the right thing by enumerating the returned fields and their ordering. It nonetheless leaves gaps an agent would hit in practice: no pagination path (the more_results sibling exists but is never referenced), no site-parameter format, and no indication of what an empty or failed lookup returns.

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 0%, so the description must carry parameter meaning. It does clarify query, site ('a website to find in the results'), the 3–30 range for limit, and implicitly the country parameter via 'as a searcher in that country sees them.' It still leaves the site format (domain vs URL) and default behavior unnamed, so compensation is partial.

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 concrete verb+resource (Google results for a search) and specifies the returned shape in order (title, site, snippet, link), plus the rank-tracking angle. It is clearly distinct from generic siblings like read_site or find_news, though it never explicitly contrasts itself with the closest alternative, more_results.

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 'as a searcher in that country sees them, and where a site ranks among them' — i.e., use this for localized SERP inspection and rank checks. However, there is no explicit when-not guidance, no mention of when to switch to more_results for pagination, and no prerequisites stated.

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?

With readOnlyHint=false and no output schema, the description carries the burden well: it explains why the call is not read-only ('Uses one read and saves the result in the user's Puley history'), discloses the batch cap, lists the upstream sources consulted (Open Library, Deezer, JustWatch, OpenAlex, Wikidata, Google Maps, Amazon US), and enumerates the possible verdicts (Real, Different details, Misattributed/Disputed, Closed, Not found, Couldn't confirm). That is substantive behavior beyond the annotations, consistent with openWorldHint=true.

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 and the verdict list are front-loaded in the first sentence, with sources and cost shoved to the back, which is the right ordering. The middle sentence is dense – a long comma-separated source roster – but each element is informative for trust assessment rather than 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 moderate-complexity, open-world lookup tool with no output schema, the description covers what to send (kinds, cap), what comes back (six verdict types plus link/details), and what it costs. It does not say how partial or per-item failures appear when only some of the 15 items resolve, which is the main remaining 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?

The top-level `things` array is undocumented in the description beyond the '15' cap, and the reported schema coverage is 0% (though the nested Thing properties do carry their own field descriptions). The description adds the batch constraint and clarifies that quotes are checked as words and people come back with description/dates, which is useful but limited relative to the ten-value `kind` enum and the `by`/`year`/`place` disambiguators.

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

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

The description opens with a specific verb + resource: 'Check whether the books, songs, albums, films, shows, papers or citations, people, quotes, places or products named in an answer really exist.' It enumerates the exact entity kinds it handles, which matches the `kind` enum in the schema, so an agent can distinguish it from look-alike siblings such as check_links, google_results, or find_news without opening any schema.

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

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

It implies the trigger context strongly ('named in an answer' – i.e. fact-checking a draft or response) and gives a hard operating limit ('Up to 15') plus a cost note ('Uses one read'). It does not explicitly name an alternative tool or state when NOT to use it, so it falls short of a 5, but the usage context is unambiguous.

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

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

With readOnlyHint=false declared, the description supplies the reason: results are 'Saved in the user's Puley history', explaining why a lookup tool is not read-only. It also discloses the data provenance ('Numbers are Google's own (Google Ads data)') and a hard input limit (up to 10 keywords) that the annotations do not cover. It stops short of describing rate limits, failure modes, or how the history entry behaves.

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 payoff (the four metrics in one table), then parameter formats, then provenance — a sensible order with little waste. The opening is a long clause chain rather than a crisp summary sentence, which slightly slows scanning.

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, and the description compensates by naming the returned columns ('in one table') and the data source, plus the 10-keyword limit. Missing are the table's actual column layout for multi-keyword input and any error or partial-failure behavior, but nothing essential to making the call is absent.

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 0%, so the description carries the full burden and does: keywords is comma-separated with a concrete two-term example and a 10-item cap, and country is specified as a two-letter code. That is meaningfully more than the bare string types 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?

The description enumerates the exact outputs (monthly search volume, cost-per-click, trend direction, related searches) delivered 'in one table', so an agent can tell what resource it gets back. The verb is only implicit ('gives you this data'), and it never distinguishes itself from the sibling search_trends, which plausibly also covers 'whether interest is rising or falling'.

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

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

Usage is only implied by the tool's subject matter; there is no statement of when to prefer it over search_trends, google_results, or find_ads, and no exclusions or prerequisites (e.g., account connection, quota). An agent can infer intent but must guess at boundaries.

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?

The annotations declare readOnlyHint=false with destructiveHint=false and openWorldHint=true; the description usefully explains the write side by noting results are 'Saved in the user's Puley history', which reconciles the non-read-only hint. It also sketches what each platform returns. It does not disclose coverage limits, rate behavior, or what happens when an advertiser isn't found, which matters for an open-world lookup.

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-loaded with what the tool returns before the parameter hints. The parenthetical source attribution and field list are dense but earn their place; minor run-on quality from stacked parentheses.

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 only four flat parameters, the description covers the core of what an agent needs: what comes back per platform and how to specify platform/advertiser. The remaining gap is the undocumented limit and country parameters, which could change result sets silently.

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 0% across four parameters, so the description must carry the load; it explains 'platform' (linkedin or tiktok) and 'advertiser' (company name, or website required for TikTok), which is genuinely additive. It says nothing about 'limit' or 'country' (default 'ALL'), leaving half the parameters undocumented anywhere.

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

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

The description names the resource (advertiser ads on LinkedIn's Ad Library or TikTok's ad/boosted-post inventory) and the fields returned (headline, text, type, start date; views and likes), so an agent can distinguish it from generic siblings like find_ads. It would be a 5 if it explicitly contrasted itself with those siblings.

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

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

It states the accepted values for platform and how to identify the advertiser, but gives no guidance on when to pick this tool versus find_ads, ugc_ad, or product_ad_pack. There are no exclusions or prerequisites mentioned.

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 safety framing is covered. The description still adds substantive context beyond them: the result set is filtered to connections explicitly enabled for AI reading, and credentials are never collected in chat — behavior an agent could otherwise get wrong by attempting a sign-in flow.

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

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

Three short sentences, front-loaded with what is listed, then the consent location, then the exclusion. The security reassurance about passwords and codes is defensible because it prevents a wrong action, though the opening phrase partly restates the title.

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

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

For a parameterless read tool with no output schema, this covers what is returned, what is excluded, and where the user-side consent happens. It doesn't indicate what a connection record contains or what an empty result means, but neither is essential to calling 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?

The tool takes zero parameters, so the schema has nothing to explain and the description has nothing to compensate for. Baseline 4 applies.

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

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

Names a specific verb and resource ('List this user's saved website connections') and narrows scope to those 'explicitly enabled for AI reading'. The distinction from the sibling read_with_account (which presumably performs the reading) is left implicit, so an agent must infer the relationship rather than being told 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 a clear when-not ('Does not connect accounts or change permissions') and routes the sign-in/consent step to manage_url in Puley. It stops short of naming a sibling to call instead when the agent's real goal is reading content through one of these connections.

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?

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds non-schema context: the call consumes no reads and the results include read costs, video image-start/sound support, and model strengths, though it does not discuss auth or rate limits.

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 dense and mostly front-loaded, with little wasted wording, but the first sentence is awkward and run-on ('with about how many reads one file uses'), making the capabilities harder to parse than necessary.

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

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

For a two-parameter listing tool with no output schema, it discloses what the result set contains: model categories, read cost, video capabilities, and what each model is good for. It does not specify output shape or default behavior, but it gives enough context to invoke the tool 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?

With 0% schema description coverage, the description carries the parameter burden. It supplies the key kind values (image, voice, video) and explains photo=true as filtering to image-start/edit models; it does not restate defaults, but it adds the missing semantic mapping.

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 identifies the resource as models for generating pictures, voice-overs, music, or videos and says it returns read costs and capabilities. It is clear what the tool lists, though it does not explicitly distinguish itself from sibling tools such as make_media.

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 useful filter guidance: kind=image, voice, or video, and photo=true filters to models that start from or edit a picture. It also notes 'Uses no reads,' implying discovery before generation, but it does not explicitly say when to use this versus make_media or another sibling.

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 covered. The description does add real value with 'No checks or charges' (it does not trigger a check run) and the next_offset pagination behavior, but says nothing about result size or ordering.

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 short sentences, front-loaded with the core action and return fields, followed by the one operational caveat. 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 carries the burden of describing returns and does so by naming the fields returned. The main residual gap is the unmentioned limit/default and ordering 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 coverage is 0% and both limit/offset carry no descriptions, so the description must compensate. It explains that next_offset yields the next page, which clarifies offset semantics, but leaves limit's meaning and default (50) unaddressed.

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 ('List the user's existing watches') and enumerates the returned fields (IDs, schedules, errors, email queue status), which cleanly separates it from get_watch (single) and check_watch_now (triggers a check).

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 checks or charges' implicitly steers the agent away from check_watch_now when it merely wants to inspect watches, and the pagination hint tells it how to continue. It stops short of naming the alternatives explicitly, so not 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?

Adds real context beyond the annotations: it enumerates the per-store payload (stock, quantity, pickup, distance, address, phone, hours, price) and discloses both the cost model ('uses one read') and the side effect ('saves the result in the user's Puley history'), which explains the readOnlyHint=false. It stops short of stating failure behavior (no nearby stores, no product match) or what happens when the product name is ambiguous.

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?

Roughly sixty words, front-loaded with the core question and with no filler. The middle clause stacking returned fields ('stock, quantity, pickup, distance, address, phone and today's hours, and the price') is a run-on that would read better as a short list, but every element 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?

There is no output schema, so the description correctly spends space describing what comes back, and it covers all three parameters plus the read-cost and history side effect. Missing only edge-case behavior and result-limit/pagination details, which are minor for a single-shot lookup 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 0%, so the description must carry all meaning, and it largely does: product accepts a link or a name with best-match resolution, radius is in miles bounded 5 to 100, and zip_code is a US ZIP. The zip_code parameter itself gets no explicit definition beyond being implied by 'near a US ZIP code'.

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 question ('whether a product is on the shelf'), a specific retailer (Target), and a specific scope (stores near a US ZIP code), with the data source named ('Target's own store check'). An agent can immediately distinguish this from siblings like compare_stores, search_marketplace, or resale_prices.

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 framing 'near me' plus the US-ZIP requirement, and the product input rule (link or name, best match used) guides invocation. However, no sibling is named as an alternative and no when-not condition is given (e.g., non-Target retailers, non-US locations, or when a general price lookup such as amazon_price_history would be preferable).

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 hints: it discloses the 500-read price threshold with the confirm=true gate, that video output is asynchronous and takes minutes, that re-asking the same prompt returns the pending/ready file and is charged once, that cost is metered by what the file cost to make, that results land in the user's Puley history, and that sexual/violent/deceptive content is rejected. Those are exactly the operational facts an agent needs before spending the user's credits.

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 one-line purpose, then grouped by kind, then by cross-cutting controls and pricing. It is dense and delivered as a single run-on paragraph, so bullet or line-break structure would aid scanning, but nearly every clause carries information specific to a parameter or behavior.

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 generation tool with no schema descriptions and no output schema, it covers mode selection, per-mode options, cost/confirm gating, latency, result location, and content policy — essentially everything needed to call it correctly and set expectations. The only soft spot is a mild tension with idempotentHint=false, since re-asking is described as returning the same job charged once.

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 0%, so the description carries the full burden and does: all 13 parameters are explained, including enumerated values for voice (narrator, british woman, comedian, etc.), emotion, quality (quick/standard/best), shape (square/portrait/story/landscape or a ratio like 4:5), a speed range of 0.5–2, named model options, seconds as video length, and the image vs image_link distinction.

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 ('Make a file from a description') and then enumerates the four distinct modes (image, video, voice, music) it produces. This clearly separates it from the neighbouring research/data siblings (find_videos, watch_video, trend_to_video) which retrieve rather than generate.

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 conditions that select each mode: image for a picture or an edit when image/image_link is supplied, video for a clip or an animated photo, voice for words read by a named voice, music for a ~30s instrumental. It also states the confirm=true precondition for jobs over 500 reads and that model may be left empty for a good low-cost default. It stops short of naming alternatives (e.g. list_models for browsing models, trend_to_video for trend-driven clips).

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?

The description explains the side effect that justifies readOnlyHint=false: the table is saved to the user's Puley history, and reads consume account limits. That is exactly the extra context annotations can't convey. It stops short of disclosing failure behavior or cost scaling with the pages 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?

A single front-loaded sentence that leads with the output and follows with constraints; no filler. It is slightly run-on with the parenthetical example list interrupting the flow, 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?

For an open-world scraping tool with no output schema, the description should say at least what comes back (a table reference? rows inline? a link to history?) and roughly how much data the pages setting can pull. It covers cost and persistence but leaves the return shape and page-limit semantics undefined.

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 0%, so the description must carry the load. It does well for fields by giving a concrete example array, and link is implied by "a page," but the pages parameter (default 3) is never explained — only a vague reference to "the page's own pagination" appears, leaving the agent unsure whether pages caps crawling or overrides site pagination.

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?

"Every product, job or listing on a page, with the fields asked for" plus "turn a page into a table" states the operation (extract structured rows from one page) with concrete examples of the fields. It is clear what the tool produces, but it never names how it differs from close siblings like read, read_site, see_page, or search_marketplace, so differentiation is left 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 describes only what the tool does, never when to pick it over the many alternatives listed (read, see_page, read_site, search_marketplace, more_results). "following the page's own pagination" hints at a use case for multi-page listings but gives no explicit when/when-not rule or alternative 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?

The annotations say readOnlyHint=false, which would otherwise look odd for a lookup; the description resolves this by disclosing 'Saved in the user's Puley history,' explaining the write side effect. It also discloses the 60-result cap and that ordering is Google Maps' own rather than a computed rank, adding real 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 compact sentences with no padding, and the core definition is front-loaded before the parameter note. The mid-sentence line break and the abrupt 'business: its name or website' fragment make it slightly less scannable than it could be.

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 state what comes back (the business's position against those above it, ordered, max 60) and the history side effect. For a 3-required-parameter tool this is nearly sufficient; cost/latency and the exact result shape remain unstated but are minor.

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 0%, so the description carries the burden: 'business: its name or website' explicitly bounds that parameter, and the 'dentist in Austin, TX' example disambiguates search (keyword) from place (location). Only finer details — address granularity, business-name matching rules — are missing.

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 operation — where a business ranks on Google Maps for a keyword+place query, in Maps' own order, capped at 60 results. That is concrete enough to separate it from find_places or google_results, though it never names those siblings.

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

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

The example 'dentist in Austin, TX' implicitly shows the intended query shape, but there is no explicit when-to-use guidance and no exclusion against the many nearby search tools (find_places, google_results, find_leads). The agent must infer the use case.

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 alone (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) would leave an agent puzzled about why a read looks like a write; the description explains this by disclosing that the call consumes one read and persists the result to the user's Puley history. It also reveals the upstream provider (Yahoo Finance) and that quote timestamps are returned. It does not say whether prices are real-time or delayed, which is the main remaining gap.

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

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

The description is front-loaded with the payload and its source, then narrows to the single argument, then to cost/persistence. It is dense but every clause carries information; the returned-field list is long but necessary 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?

With a 0%-covered single parameter and no output schema, the description compensates on both fronts — it fully specifies the argument and enumerates the returned fields (price, session change, day and 52-week range, volume, exchange, quote time). Only the real-time vs delayed nature of the feed is left 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 0%, so the description must carry the parameter alone, and it does: cardinality (up to 10), delimiter (comma-separated), three symbol dialects with concrete examples (AAPL, NPN.JO, ^GSPC, EURUSD=X, BTC-USD), and the fallback of company/asset names. This is more than the bare schema could convey.

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

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

The description names the specific resource (live quotes for shares, ETFs, indices, currencies, crypto) and the exact data source (Yahoo Finance), so an agent knows precisely what it returns. The asset-class enumeration also separates it from narrower siblings like drug_prices, resale_prices, or subscription_prices.

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 supplies concrete invocation context — max 10 comma-separated symbols, accepted symbol formats per exchange, and that plain names (Apple, bitcoin, gold) also work — plus a cost signal ('Uses one read'). It stops short of stating when to prefer a sibling such as local_stock or app_charts, so there are no explicit 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 readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered. The description adds genuinely new behavior: it reads from the user's saved Puley history and consumes no read allowance, and find/sort_by apply across the whole saved table rather than just the returned page. It stops short of describing failure behavior for an invalid or expired cursor.

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 core purpose and the cursor contract, then behavior, then filtering options — a logical order with no filler. The awkward line break mid-sentence and the parenthetical examples make it denser than it needs to be, 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 correctly takes on the return contract (next rows or text plus another cursor until complete is true), which is what an agent needs to loop. The remaining gap is error/expiry handling for the cursor, minor for an idempotent read tool.

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

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

Schema coverage is 0%, so the description must carry all parameter meaning and it does: cursor is sourced from completeness.more.cursor, find matches rows containing every comma-separated term (AND semantics, shown with an example), sort_by orders by exactly one column with an example, and descending selects highest-first. This is meaning well beyond the bare schema titles.

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 next part of a Puley result that was too long for one answer" states a specific resource and the exact condition that makes this tool applicable (completeness.complete is false). No sibling tool in the list covers pagination of a saved result, so it is distinguishable, though the description never names the tool that produced the truncated answer (read/read_site/etc.) to close the loop.

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 an explicit trigger (completeness.complete is false) and tells the agent exactly where the required argument comes from (completeness.more.cursor from that answer), plus the loop condition (until complete is true). It does not state when NOT to use it — e.g. what to do if the cursor is stale or the result has expired.

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?

The description resolves the notable annotation tension: readOnlyHint=false is explained by 'Uses one read and saves the result in the user's Puley history', so the agent learns the call has a side effect (history write) plus a read cost, while destructiveHint=false remains consistent. It also discloses data freshness (weekly) and what each scope returns (views/hours viewed vs weeks in Top 10), which goes beyond the annotations. Minor gap: no mention of failure behavior or how much history is retained.

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?

Resource and freshness are front-loaded, and the parentheticals pack in scope variants without filler sentences. The nested parentheses ('for the world (global, with views..., in English or non-English) or a country (...)') make one sentence harder to parse than necessary.

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?

Three optional parameters, no output schema, and a modest tool surface – the description covers all three inputs, the freshness of the data, the read cost and the history side effect. An agent has enough to call it correctly; only edge details (invalid country codes, language-not-applicable cases) are unstated.

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

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

Schema coverage is 0% with no enums, so the description carries the full burden and largely does: kind is 'movies or tv', country is 'global' or a two-letter code with concrete examples (us, gb, za, in, br, jp, kr...), and language is 'english or non-English'. It also ties the country choice to different return fields. It stops short of an exhaustive value list (the '...' leaves accepted codes open) and doesn't clarify whether language is ignored for country queries.

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 (Netflix's own weekly Top 10) with an explicit scope split (global vs country, movies vs tv) and freshness ('right now'). It is clearly distinguishable from siblings such as where_to_watch or app_charts without opening any schema.

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

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

Adds a usage cue ('Shows what's popular or trending on Netflix'), which implies when to reach for it, but never names an alternative or states when not to use it. With a sibling list containing where_to_watch, app_charts and find_videos, an explicit boundary would be valuable and 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?

Beyond the annotations, the description discloses that execution is asynchronous, that later runs suppress posts already listed by earlier runs, that drafts are produced for the user to post, and that nothing is published on the user's behalf. That last point meaningfully reinforces destructiveHint=false. There is a mild tension: 'the same request again returns its progress or the finished list' sounds close to idempotent, while idempotentHint=false declares otherwise, though this reads as a polling affordance rather than a real 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?

The core explanation is front-loaded and reasonably tight, but the structure is jumbled: parameter glosses are dropped mid-paragraph, then the text returns to the polling behavior. 'Puley posts nothing' arrives as an unexplained brand reference, and one sentence is missing an article, which makes the text slower to parse than it needs to be.

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 asynchronous, no-output-schema job, the description covers the essentials: what triggers it, what it produces, that it runs in the background, and how to retrieve results by re-calling. It does not say where or in what shape the finished list arrives, how long a run typically takes, or what happens if no matching posts are found.

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 0%, so the description carries the full burden of explaining the parameters, and it gives only thin glosses: 'what: what is sold' and 'offer: a line about the person's offer.' It does not say how granular 'what' should be, or how long 'offer' should be, or what the empty default means. An agent can guess, but the semantics remain underspecified.

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 concrete verbs and resources: finds posts on Reddit and X where people ask for what the user sells, and drafts a first reply for each. That is far more specific than the tool's name 'new_buyers' and lets an agent distinguish it from read-only search siblings like search_posts or people_asking. It never explicitly says which sibling to prefer, though, 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?

It gives useful invocation context: it runs once in the background, and calling again returns progress or the finished list. That effectively tells the agent not to re-invoke to poll for new work. It never says when to choose this over the many related research or search siblings, and it never states prerequisites, such as whether Reddit or X accounts must be connected first.

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?

The description adds real context beyond the annotations: 'Uses one read (two to compare)' discloses a credit/consumption cost, and 'saves the result in the user's Puley history' explains why readOnlyHint is false on an otherwise read-like operation. openWorldHint and idempotentHint behavior are left unaddressed, and no fallback behavior is described if an archive has no snapshot.

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 scope statement, then branches on `since` and `show`, with the user-question framing at the end. Dense but every clause carries information. Minor cost: the parenthetical and nested clauses make the second sentence a bit run-on.

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 indicates what results look like (change summary vs. historical snapshot vs. archive timeline) and notes the read cost. Remaining gaps are small: no snapshot-found behavior, no result format or size expectations. Overall adequate for a three-parameter archival lookup.

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 0%, so the description has to carry the parameters, and it does explain `since` ('2024, 2024-06-30 or 1 year ago') and the `show=page` mode usefully. However the `show` parameter's default and other values are only implied, and `link` is never characterized (URL form, required). It partially but not fully compensates for the coverage gap.

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: retrieving a page's past from web archives (Wayback Machine, then Common Crawl), plus diffing between then and now. That is far more specific than a name restatement. It does not explicitly name a sibling such as whats_changed or see_page to draw the boundary, 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?

Gives concrete when-to-use branches: with `since` it answers 'did they change their prices or terms?', with `since` + `show=page` it shows the page as it was, and without `since` it lists archive dates. It also frames the user questions it answers. It never states when to prefer a different tool instead.

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?

Adds real value beyond the annotations: it names the destructive consequence (in-progress results are discarded), warns of residual side effects (queued emails may already be sent), and states the required permission. This is consistent with destructiveHint=true and idempotentHint=true. It could go further by noting whether the pause is reversible or how state is restored via resume_watch.

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

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

Three short sentences, front-loaded with the action and its primary effects, then the caveat and the permission requirement. No filler or restatement of the tool name.

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

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

For a single-parameter mutation, the description covers the essential behavior, side effects, and auth requirement, and the annotations supply the safety profile. The remaining gap is practical: how an agent obtains a valid watch_id and whether the pause can be undone.

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

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

There is one parameter (watch_id) with 0% schema description coverage, and the description does not explain it, only referring vaguely to "a watch the user chose." It gives no hint about where a watch_id comes from (e.g., list_watches/get_watch) or what format it takes.

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?

Uses a specific verb+resource ("Pause a watch") and immediately specifies the two effects: "stop future checks and discard any in-progress result." This distinguishes it from destructive siblings like delete_watch and from resume_watch by implication, though no sibling is named explicitly.

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

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

The usage context is implied by the effects described (temporarily halt checks), but the description never states when to choose pause over delete_watch or when to resume instead. No prerequisites or exclusions are given beyond the permission note.

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?

The annotations declare readOnlyHint=false, which is counterintuitive for a search-style tool; the description usefully explains this by noting results are 'Saved in the user's Puley history', and it discloses the source platforms and that output includes a reason and a link. It still leaves out practical traits such as result volume, credit/cost implications, and whether the history write is per-call or per-unique-result.

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 output shape and behavior are front-loaded in the first sentence, followed by compact parameter notes. The 'what:' / 'period:' label style is terse and slightly ungrammatical but wastes no words.

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 only two parameters and no output schema, the description needs to cover both inputs and the return shape, and it does: ranked posts with a buy-readiness rationale and a link, plus persistence to history. It stops short of stating result limits or pagination, but an agent can call it correctly from what is given.

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 0% and 'period' is an unconstrained string, so the description carries the load: it supplies the enum-like value set (day, week, month, year) that the schema omits, plus a clarifying example for 'what' (bookkeeping for freelancers). Minor gap: it doesn't specify how 'what' should be phrased or whether period bounds post date or the search window.

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

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

The description names the concrete resource (public posts on Reddit and X where someone asks for a recommendation) and the ordering principle (ranked by readiness to buy), which is far more specific than the vague title 'People asking for it'. It does not explicitly distinguish itself from lead-gen siblings such as find_leads or new_buyers, but the sourcing and intent-ranking make the scope unmistakable.

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 statement and no named alternative, even though several siblings (find_leads, new_buyers, search_posts) occupy adjacent territory. The agent must infer the use case from 'ranked by how ready they are to buy', which is implied guidance at best.

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?

Beyond the supplied annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses genuinely useful behavior: asynchronous background execution, status-by-replay polling, email delivery of the result, and per-file billing of roughly $1–$2. The only soft spot is that 'the same request again returns its progress' sits in mild tension with idempotentHint=false, since an agent could read it as a free safe retry; it is a nuance rather than a direct 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?

The main action is front-loaded in the first clause and the remaining sentences are compact parameter hints with no filler. It reads as a slightly run-on block rather than a structured list, which costs a little scannability but wastes no words.

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?