SnoopScan

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

Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true), so credit goes to additions: the job returns an id immediately rather than results, pages are billed individually, and a free API key is required. These are non-obvious operational facts an agent needs; only the polling cadence/expiry of the job id is 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?

Three short sentences that front-load the batch limit, then the async return contract, then the billing/auth caveats. Efficient, but the orphaned 'Needs a free SnoopScan key.' line reads as an afterthought rather than integrated guidance.

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?

An output schema exists, so return values need not be described, and the description still covers the async job-id contract, the polling follow-ups, billing, and auth. Nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 0% and the single `urls` array is undocumented in the schema, so the description must carry the load. It does supply the key semantic constraint (maximum 50 URLs per call), though it adds nothing about URL format, duplicates, or per-URL error behavior.

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 (Scrape), resource (pages), and hard scope limit (up to 50) as one background job. It explicitly distinguishes itself from the single-page sibling `scrape`, so an agent can route correctly without inspecting schemas.

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?

Names the alternative explicitly ('For one page, use `scrape`') and the condition that selects it (batch vs single). It also gives the follow-up path (`crawlStatus`, `crawlPages`), though it doesn't state when *not* to use batch scraping beyond page count.

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 readOnlyHint=false, idempotentHint=true, openWorldHint=true, and the description usefully reconciles the write behavior by disclosing that a changed page is stored as the new latest version. It also adds the auth prerequisite ("Needs a free SnoopScan key"), which annotations do not cover. It stops short of describing rate limits or storage retention/overwrite consequences beyond the latest-version statement.

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 mechanism, then the includeDiff effect, then the auth requirement. Every sentence adds information and nothing is repeated from the schema or 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?

An output schema exists, so return-value detail is not required here. The description covers the action, the storage side effect, the first-check edge case, the includeDiff behavior, and the key requirement, which is enough for correct invocation; only the absence of sibling routing guidance leaves it just short of fully complete.

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 semantics. It does explain includeDiff (current content returned when the page changed) but gives no format, canonicalization, or validation guidance for url beyond the obvious, leaving one of two params only implicitly documented.

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

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

States a specific verb+resource ("Check whether a page has changed") and explains the mechanism (fetches now, compares to latest stored version), which meaningfully separates it from plain scrape/fetch siblings. It never names an alternative tool (e.g. watchPages, checkMonitor) to complete the differentiation, so it lands at 4 rather than 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 contextual facts that guide use (first check of a URL reports it as new; includeDiff returns current content), which implies this is for one-off change detection. It never says when to prefer this over watchPages/checkMonitor or when not to use it, so the guidance is implicit 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?

Adds real context beyond the annotations: it discloses the billing consequence ("Billed like a scheduled check") and an auth prerequisite ("Needs a free SnoopScan key"). Annotations already cover readOnly=false, openWorld=true, idempotent=false, so the incremental disclosure here is the cost and credential profile, which matters for a non-idempotent action.

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 action and the result categories, then the two operational caveats. Very short and every sentence earns its place, though the fragmented blank-line layout makes the credential note read like an afterthought.

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?

An output schema exists so return values need not be detailed, and the description still previews the outcome categories. Billing and auth are covered; the only meaningful gap is where monitorId comes from and what happens on a failing/invalid monitor.

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 the description never explains monitorId — how to obtain it, its format, or whether it must come from listMonitors. It only implies the parameter identifies "a monitor," which is already obvious from the name; nothing 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+resource ("Run a monitor's check now") and enumerates the outcome classes reported (new/changed/unchanged/failing), which is more than a restatement of the title. It differentiates from listMonitors by being an execution action rather than a listing, though it never explicitly names a sibling it is not.

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 phrase "check now" suggests forcing an out-of-band run versus the scheduled checks, and "Billed like a scheduled check" hints at a cost tradeoff. No alternative (listMonitors, watchPages, checkChanges, crawlStatus) is named and no when-not condition is 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?

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the description correctly focuses on what those hints don't cover: the crawl scope ('homepage and a few contact/about pages, nothing behind a login'), the one-at-a-time constraint, and the auth requirement ('Needs a free SnoopScan key'). No rate limits or failure modes are mentioned, keeping it 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?

Three short, purposeful paragraphs with the returned-fields detail grouped together and the alternative-tool pointer at the end. The opening line is somewhat atmospheric rather than operational, and the auth-key requirement ('Needs a free SnoopScan key') is buried last where an agent would rather see it before committing to a call.

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 an output schema present, return values needn't be explained, and annotations cover the safety profile; the description fills the remaining gaps around crawl scope, single-company operation, auth needs, and the sibling alternative. The one real omission is the undocumented `contacts` parameter, which is more a parameter-semantics issue than a completeness failure.

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 parameters. The description implies the `url` input ('Give it a company domain') but never states the format, and it says nothing at all about the `contacts` boolean, which materially changes the response. With coverage this low the description must compensate and it only does so for half the parameters.

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

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

The description states a specific resource and action – profiling a company's own website – and enumerates the returned fields (name, phone, address, LinkedIn, headcount, industry, founded year, emails, socials, contact form). It explicitly distinguishes itself from the sibling `findLeads` by contrasting 'profiles one company at a time' with 'find businesses by trade and place'.

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 names the alternative tool and the condition that selects it ('To find businesses by trade and place, use findLeads'), and implies the when-not boundary with 'nothing behind a login.' It does not address other plausible siblings like `domain`, `people`, or `scrape`, so the routing guidance is clear but not exhaustive.

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 annotations only covering safety/idempotency flags, the description adds genuinely new behavioral context: asynchronous execution with an immediate job-id return, multi-minute latency, per-page billing, and that `limit` bounds page fetches. The authentication requirement is also disclosed. This is a strong disclosure layer over thin 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?

Three short, front-loaded statements with no filler: what it does, how it behaves asynchronously, and what it costs. The trailing auth line is terse but earns its place as a hard prerequisite.

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?

An output schema exists, so return values need no prose, and the async workflow, billing, and auth are covered. The remaining gap is the crawl-scoping model (depth, include/exclude paths), which the description never touches and which the schema does not explain either.

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 five parameters; it only explains `limit` (and does so usefully, tying it to billing). `url`, `maxDepth`, `excludePaths`, and `includePaths` receive no semantic explanation anywhere, leaving the depth and path-filtering model entirely opaque.

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?

"Start crawling a website" gives a specific verb and resource, and the description situates the tool precisely in the crawl workflow by naming `crawlStatus` and `crawlPages` as the follow-up steps. It stops short of differentiating itself from true alternatives in the sibling set such as `scrape`, `batchScrape`, or `map`, which an agent might equally consider.

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 tells the agent the operational context well: it runs in the background, returns a job id immediately, and must be followed by `crawlStatus` and `crawlPages`. The prerequisite (a free SnoopScan key) is stated. It offers no explicit when-not-to-use guidance or routing away from sibling tools that also fetch pages.

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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuine context beyond them: the response is paginated, a cursor is returned for continuation, and a free SnoopScan key is required. It still withholds rate limits or result-size behavior for limit/maxCharsPerPage.

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 read action and the pagination rationale, then the auth prerequisite. No filler; each sentence 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?

An output schema exists so return values need not be explained, and pagination/auth are covered. But for a 4-parameter tool with 0% schema coverage, the description omits what jobId identifies and what limit/maxCharsPerPage control, leaving the agent underinformed.

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, but it only explains cursor (pass the returned cursor to continue). jobId, limit, and maxCharsPerPage are left entirely undocumented, so most parameters have no semantic guidance 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?

States a specific verb and resource ('Read the pages a crawl has collected'), which clearly distinguishes it from crawl (which initiates a crawl) and crawlStatus. It does not, however, explicitly name a sibling it is not, 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?

Implies the tool is used after a crawl exists by describing the output as belonging to 'a crawl has collected', and it notes the SnoopScan key prerequisite. But it never states when to use this rather than scrape, fetchMore, or crawlStatus, leaving the agent to infer placement in the workflow.

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 and non-destructive behavior, so the safety profile is covered. The description adds genuine context beyond them: what it returns (counts and cost, never page bodies) and the required free API key, neither of which appears in 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 short sentences, front-loaded with the core action, followed by the return-content boundary and the auth requirement. Every sentence earns its place with 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?

An output schema exists, so return values need not be detailed, and the description still adds a useful return-shape note plus the API-key requirement. The remaining gap is not explaining the `jobId` parameter's origin, which an agent needs to call it correctly.

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

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

There is a single required parameter, `jobId`, with 0% schema description coverage, and the description does not explain what it is or where it comes from (presumably the output of the `crawl` tool). Since coverage is low, the description was responsible for compensating and does not.

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+resource ("check the progress of a crawl") that is distinct from the sibling `crawl` (which starts one) and `crawlPages`. It is clear what the tool does, though it does not explicitly name or contrast against 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 only implied — an agent infers this is called after a crawl is initiated, but there is no explicit when-to-use or when-not-to-use guidance. The "Needs a free SnoopScan key" prerequisite is useful context but is a setup requirement rather than usage 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 already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds two genuinely new traits: it does not fetch the target page so it cannot be blocked/rate-limited on the site, and it requires a free API key. Those are useful operational facts the 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?

Short paragraphs, lead sentence front-loads the payload, and each clause adds information. Slightly conversational phrasing and the standalone API-key line cost it a point 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?

With an output schema present, return values need no explanation, and auth is covered. However the 0%-coverage parameter set is left largely unexplained and no sibling differentiation is given, so an agent has real gaps before it can call this confidently.

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% with three parameters. The description only loosely gestures at `backlinks` ('who links to it') and never explains `limit` or the expected `url` format, so it fails to compensate for the near-total absence of parameter documentation.

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

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

States a specific resource and enumerates what is returned (age, registrar, hosting, backlinks), and cleanly frames it as off-page data versus a page scrape. It does not, however, distinguish itself from close siblings like domainReport, domainScreen, or domainSnapshots, so an agent cannot route among the domain-* tools from the description 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?

Gives concrete trigger scenarios ('comparing competitors, judging a source, checking whether a domain was registered last week') and an explicit when-not via contrast with a page scrape. It never names an alternative sibling tool, which caps 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: the free SnoopScan key requirement (auth), the flat per-depth pricing, and the 6/12 archived snapshot counts that affect runtime.

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 deliverable, then the depth semantics, then pricing and the key requirement. Efficient overall, though the trailing one-line 'Needs a free SnoopScan key.' sits slightly apart from the flow.

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?

An output schema exists so return values need not be described, and annotations cover the safety profile. Depth, pricing, and the auth prerequisite are covered, leaving only sibling disambiguation 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 coverage is 0%, so the description carries the burden and does so well for `depth`, spelling out what quick, buyer, and deep each add and their archive-sample sizes. The `url` parameter is left implicit, which is a minor gap given its obviousness.

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: a buyer's report on a domain covering key findings, concerns, and unanswerable questions. It is clear and distinct in tone, but never explicitly differentiates itself from close siblings such as domain, domainScreen, or domainSnapshots.

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 depth tiers (quick/buyer/deep) give strong implied guidance about scope, and 'before buying it' implies the acquisition use case. However, there is no explicit when-to-use versus the many related domain* siblings, nor any exclusion guidance.

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

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

Annotations already declare a safe read-only, idempotent, open-world call, and the description adds real context beyond them: the no-website-fetch guarantee, the credit cost model (1 credit per registry-answered name, free for invalid/duplicate/unanswered), and the API-key requirement. These are exactly the operational facts an agent needs before invoking at scale.

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 blocks: what it does, the routing advice, then the return values and cost. Purpose is front-loaded, and every sentence earns its place with no repetition of structured fields.

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?

Even though an output schema exists, the description summarizes the four possible statuses and why one appears, plus auth and billing prerequisites. Combined with the annotations and the 500-name limit, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It usefully adds the 'up to 500 domain names' cap for the names array and mentions DNS/registry sources, but the boolean `dns` parameter — its default of true and what toggling it changes — is never explained.

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 — screening a list of domains for registrability — and explicitly scopes the check to registry RDAP records and DNS, plus a clarifying negative ('Nothing is fetched from the names' websites'). It is clearly distinguishable from the sibling domainReport, which it names as the follow-up rather than a substitute.

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 explicit when-to-use ('cut a long list of candidate or dropping names down to a shortlist') and names the alternative for the next step ('then run domainReport on the few that matter'), so the agent knows both the trigger and the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuinely new behavior: the billing model (free for snapshots a buyer/deep report included, charged only for ones actually fetched) and an auth requirement (a free SnoopScan key). It also previews the returned content. Only the exact charged-credits mechanics are 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?

Purpose is front-loaded, which is good, but the prose is wordy and the line breaks/phrasing ('A buyer report answers at once with the Internet Archive's timeline and the snapshots already held') are convoluted for what is a simple dependency explanation. Billing and auth details are useful but 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?

An output schema exists, so return values needn't be explained, yet the description still previews them helpfully. Auth and cost behavior are covered and the report dependency is clear; the only real hole is the unexplained 'snapshots' parameter against 0% schema coverage.

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 parameter meaning. It loosely covers 'url' ('the same domain') and 'years' ('optionally the pending years'), but never mentions the 'snapshots' integer parameter (default 6), leaving one of three parameters completely 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+resource: reading archived homepage snapshots left pending by a buyer domainReport. It explicitly positions itself relative to the sibling domainReport (which returns the timeline and held snapshots 'at once'), so an agent can tell them apart without opening either schema.

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

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

Gives the exact triggering condition ('snapshots a buyer domainReport left pending') and how to call it ('same domain, and optionally the pending years'). The alternative path (use domainReport for the immediate timeline/held snapshots, this for the rest) is named, leaving little 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 establish read-only, idempotent, non-destructive, open-world behavior, and the description usefully adds that output is validated against the schema and that a page without required fields returns an error rather than invented values. It also discloses the 'free SnoopScan key' auth requirement, adding real context beyond structured fields.

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

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

Front-loaded with the core action, then the validation/error contract, then the credential requirement. The content is tight and every sentence carries weight, though the trailing key requirement reads slightly as an afterthought.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description covers the main behavior and error semantics well; the only omission is the optional 'prompt' parameter's role.

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. It explains the schema param (a JSON schema to validate against) and the urls param ('one or more pages'), but the optional 'prompt' parameter is never mentioned, leaving a 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 (extract), resource (structured data from one or more pages), and mechanism (per a JSON schema), so the operation is unambiguous. However, it never distinguishes itself from close siblings like parse, scrape, or batchScrape, leaving the agent to infer the boundary.

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

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

No when-to-use or when-not-to-use guidance and no named alternative, despite several overlapping siblings (parse, scrape, batchScrape). The only implied usage is that a JSON schema and pages are supplied; the agent gets no help choosing this over neighbors.

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 is covered. The description adds genuinely new behavior beyond them: it re-truncates if the section is still too long, and it discloses an auth requirement ('Needs a free SnoopScan key'), which 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?

Front-loaded with the core action, three short sentences, no filler. The trailing auth note is a slightly dangling fragment rather than integrated prose, but it still 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?

An output schema exists, so return values need not be spelled out, and the description still covers the key return behavior (next section, possibly truncated again). The only real gap is the undocumented maxChars parameter and lack of explicit sibling routing.

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 explains where the required token comes from (a truncation marker), but says nothing about maxChars or its 20000 default, leaving half the parameters undocumented in both places.

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 action (read the remainder of a truncated page) and the continuation semantics clearly enough that an agent can tell this is not scrape/crawl but a pagination follow-up. It does not explicitly contrast itself with any sibling tool, so it falls short of a 5.

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

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

It implies the trigger condition — you call this after a page was truncated and you hold a truncation-marker token — which is useful implied usage. However it never states when not to use it or which sibling to prefer when starting a fresh read, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the auth prerequisite ('Needs a free SnoopScan key') and the shape of the results (contact form vendor, email provenance, social links). It doesn't mention rate limits or what happens on unreachable sites, but it clears the lowered bar set by 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?

Roughly four short lines, front-loaded with the purpose, then returns, then the auth requirement. No filler and no restatement of the title in prose form.

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?

An output schema exists, so return values are formally documented, and the description still summarizes them plus the API-key prerequisite. The main residual gap is how errors or sites without contact pages are handled, and slight redundancy with the output schema.

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

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

One parameter, 'url', with 0% schema description coverage, so the schema carries no semantic detail. The description only implies the value is a company website URL ('for a company website'), adding no format, protocol, or scope guidance. Adequate but not compensating 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?

A specific verb+resource ('Find contact information for a company website') that an agent can distinguish from sibling tools like company, people, or findLeads. It also enumerates the returned artifacts (contact page, form + vendor, emails with provenance, social links). It stops short of explicitly naming which sibling to prefer, but the resource is narrow enough to be unambiguous.

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

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

Usage is implied by the purpose rather than stated: there is no explicit 'use this when you need contact/enrichment data, use X instead' routing against siblings such as company or findLeads. The agent can infer the fit from the description, but no exclusions or alternatives are 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?

Goes well beyond the annotations: it discloses that the call runs asynchronously for 2-5 minutes (an agent must not expect inline results), that it is charged per lead delivered and never for leads it cannot find, and that it requires a free SnoopScan key. These are exactly the operational facts an agent cannot get from readOnlyHint/openWorldHint/idempotentHint.

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 core purpose, then walks parameters in a logical order, then ends with the async/cost/auth constraints. Slightly dense with backticked identifiers and one stray blank line, 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?

For a 9-parameter async tool with an output schema, the agent gets the discovery semantics, the polling handoff to leadsStatus, the cost model, and the auth requirement. The only real shortfall is the three undocumented parameters (limit, sources, requireWebsite), whose effect on results the agent must guess.

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 gives real semantics for who, where, country (ISO code, inferred from where when omitted), contacts, roles, and questions (up to three, answered from each business's own site with a quoted line and page). It leaves limit, sources, and requireWebsite undocumented, which is a genuine but partial 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 ('Find businesses by what they do and where') plus what each result carries (reachability, contacts, named roles, answered questions). It is much clearer than a bare 'find' tool, but it never distinguishes itself from the adjacent sibling findContacts, which an agent could easily reach for instead.

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 from the parameter semantics (business discovery by trade + location with optional enrichment), and it explicitly routes the follow-up step to leadsStatus with the job id. However there is no when-not guidance and no comparison against findContacts, searchPlaces, or company, so sibling selection 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 read-only/open-world/idempotent/non-destructive, yet the description adds substantial behavioral context: AI Overview is only read where a paid provider is configured, otherwise a classic organic list of up to 10 results with a note, billing per search with no charge on empty results, and a free SnoopScan key requirement. This is real value beyond the annotations.

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

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

Front-loads the core purpose and packs billing, auth, and fallback behavior into a compact block. Slightly run-on, but nearly every sentence earns its place with 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 an output schema present, return values needn't be described. For a read-only SERP tool, the description covers the auth requirement, billing model, provider-dependent AI Overview behavior, and result-count fallback — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the param burden. It clarifies `domain` and gives a format example for `country` ('two-letter code such as gb'), but `depth` and the `aiOverview` boolean toggle are never explained ('up to 10 results' only loosely hints at depth), leaving two of five params 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?

States a specific verb and resource ('Read a Google results page for a search: who ranks, and what the AI Overview says and cites'), which is a distinct purpose from the generic 'search' sibling. An agent can tell this is a SERP/ranking check rather than a general web search.

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

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

Gives clear context for use ('Give your domain and the answer says where it ranks and whether the AI Overview cites it') and explains the AI-Overview-vs-organic fallback condition. However, it never names an alternative sibling (e.g. search) or states when NOT to use this tool, so it stops short of explicit 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 already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, yet the description still adds real value: it discloses the failure mode ('Not every company exposes a feed... it says so and names the careers page'), warns that 'No feed found' does not equal not hiring, and states an auth prerequisite (a free SnoopScan key).

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, and each subsequent sentence earns its place by covering mechanism, failure behavior, and auth. It is slightly paddier than necessary but has no wasted 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?

An output schema exists, so return values need not be explained. For a one-parameter, read-only lookup, the description covers purpose, mechanism, failure semantics, and the API key requirement, leaving only the domain-vs-URL input ambiguity unresolved.

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 coverage at 0% for the single 'url' parameter, the description must compensate. It does clarify intent ('Give it a company domain'), but leaves ambiguity between a bare domain and a full URL, which the schema does not resolve either.

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

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

The description gives a specific verb+resource ('What a company is currently recruiting for') and the title reinforces it ('Find a company's open jobs'), plus it explains the mechanism (careers page -> ATS -> public job feed). It is clearly distinguishable from siblings like 'company' or 'domain', though it never explicitly names an alternative.

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

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

It tells the agent what to pass ('Give it a company domain') and describes the failure mode, which implies the usage context. However, there is no explicit when-to-use vs when-not-to-use guidance and no sibling alternative is named for the cases where a feed isn't available.

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 and non-destructive, so the safety profile is covered; the description adds genuinely new behavior: this is an asynchronous job whose call returns a stage while running and data only on completion, results arrive in batches of 25, and a free SnoopScan key is required. It does not mention polling cadence or terminal/error states, which keeps it from 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?

Three short sentences, front-loaded with the tool's job, then return behavior, then the auth requirement. No filler or 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?

An output schema exists so return field documentation is optional, yet the description still enumerates the returned fields and the batching model, and it flags the API key requirement. Only the lack of guidance on polling intervals or how to detect a failed run leaves a minor gap for an async job 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 carries the burden, and it explains `offset` concretely (fetch the next 25) rather than just naming it. `jobId` is only indirectly characterized as the identifier of a Find Leads run, leaving its provenance slightly implicit.

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 resource ('Follow a Find Leads run, and read its leads'), and its name/behavior clearly separate it from the sibling findLeads, which starts a run rather than reading one. An agent can tell this is the read/poll counterpart without opening either 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 clear operating context: poll while the run is in progress, then page through results with `offset` 25 at a time. The prerequisite (a Find Leads run must exist) is implied by 'Follow a Find Leads run' rather than stated explicitly, and no exclusions or alternative tools are named, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds sorting order (newest first), the returned fields, the no-watchId fallback, and an auth prerequisite ('Needs a free SnoopScan key') – useful context beyond the annotations.

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

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

Front-loaded with the core action, then filters, then edge-case behavior and auth note. The embedded enum lists are long but informative; structure is efficient with little waste.

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

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

With an output schema present, return values needn't be spelled out, and the description covers filtering, ordering, fallback, and auth. Only the limit/pagination behavior 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 load. It documents category and status enum values, the watchId scoping, and platform filtering – but the `limit` parameter and its default (20) are 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?

States a specific verb and resource ('List the mentions this account's watches have found') with scope detail (newest first, each with category and deciding phrase). This clearly distinguishes it from mutation/other siblings like markMention or watchMentions.

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

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

Explains the filtering conditions (watchId, category, platform, status) and the no-watchId fallback behavior. However, it does not explicitly contrast with variants like testMentions or watchMentions, so the alternative-selection guidance is implicit 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds context the annotations do not: it discloses an authentication prerequisite ('Needs a free SnoopScan key') and what the returned records contain, which is genuine added value for an agent deciding whether it can call it.

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: the purpose/scope statement first, the prerequisite second. No filler, no restating the title, every sentence 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 a zero-parameter, read-only listing tool with an output schema present, the description supplies everything an agent needs: what is listed, what the records include, and the auth requirement. Return-value detail is appropriately left to the output schema.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly says nothing about arguments, avoiding noise.

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 this account's page monitors') and adds what the listing contains ('their schedule and when each last ran'), which is more than a restatement of the name. It does not differentiate itself from near siblings like checkMonitor or watchPages, 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?

The phrase 'this account's' implies the scope of use, but there is no explicit guidance on when to pick this over checkMonitor (single monitor status) or watchPages (create a monitor). Usage must be inferred from the name and the monitor/watcher sibling cluster.

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 open-world behavior, so the safety profile is covered. The description adds real value beyond them: which backends are tried first (API for known platforms, RSS/Atom otherwise), the fields returned, and the API-key requirement.

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 backend detail, then the routing hint and auth note. Slightly fragmented across line breaks but every sentence earns its place; 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?

An output schema exists, so return values need not be explained, and the auth/backend context is useful. However, with 0% parameter coverage and two undocumented parameters (notably `limit`), the definition is not quite complete for correct invocation.

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. It implies `url` is the site address but never names or explains it, and the `limit` parameter (default 100) is entirely undocumented in both schema and prose. The description adds only the faintest parameter meaning.

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

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

States a specific verb (list) plus resource (posts/articles) and names the mechanisms (site's own API vs RSS/Atom), including concrete platforms (WordPress, Substack, Squarespace, Discourse). It also distinguishes itself from the sibling `scrape`, so an agent can tell the two apart without opening a schema.

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

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

It routes the agent explicitly: use `listPosts` to enumerate posts, use `scrape` on a URL to read a single one, and it states the auth precondition (needs a free SnoopScan key). It lacks an explicit when-not/no-post-site exclusion, so it falls just short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds valuable non-annotation context: works without a key for Shopify/WooCommerce, one request per page up to 250 products, and requires a free SnoopScan key. It does not contradict annotations.

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

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

Front-loaded with the core purpose, then capabilities, then the key requirement. Structured in short paragraphs. The odd line break before 'Needs a free SnoopScan key' is minor but does not hurt readability much.

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?

An output schema exists, so return-value details need not be repeated, and the description confirms the return fields without over-explaining. It covers platform support, pagination, and auth requirement. It could more explicitly state the required url parameter's intent and limit's default, but it is substantially complete.

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 schema provides no parameter descriptions. The description compensates by explaining pagination ('one request per page of up to 250 products'), which gives meaning to the limit parameter, and implies the url targets a store catalog. It stops short of documenting the limit default or format specifics, so not 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 ('List every product a store publishes, from the store's own catalog'), and scopes it to a store's catalog, distinguishing it from generic listing siblings like listPosts and listMonitors. An agent can tell this is product enumeration, not scraping or monitoring.

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?

Implies usage by stating it works for Shopify and WooCommerce without a key and noting pagination, but never says when to use this over siblings like scrape, extract, or map. No explicit exclusions or conditions are 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?

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds two pieces of non-redundant context: that no page content is fetched, and that a free SnoopScan API key is required — an auth prerequisite the annotations do not convey.

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

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

Three short, front-loaded sentences with no filler; the core behavior leads and the auth note trails. Slightly tighter phrasing could merge the second and third sentences, 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?

An output schema exists, so return values need no explanation, and the auth requirement is stated. However, for a 3-parameter tool with zero schema description coverage, leaving 'limit' and 'search' entirely undefined makes the definition incomplete for correct invocation.

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 three parameters, so the description carries the full burden — and it documents none of them. 'limit' and 'search' are never mentioned, and their purpose (result cap, URL filtering) must be guessed from the bare property names.

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

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

States a specific verb and resource: 'List the URLs on a website without fetching page content.' The clause 'without fetching page content' implicitly separates it from scrape/crawl, though it never names a sibling tool explicitly, so an agent still has to infer the contrast.

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

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

'Use it to see a site's structure before choosing which pages to scrape' gives a concrete when-to-use scenario. It stops short of naming an alternative tool or stating when this is the wrong choice (e.g., when you already need page content).

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 this is a non-read-only, idempotent, non-destructive write, so the safety profile is covered. The description adds the auth prerequisite (free SnoopScan key), which is genuine behavioral context, but says nothing about failure modes or whether marking is reversible.

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

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

Two tight sentences with zero filler, front-loading the action and its valid values before the prerequisite. Nothing extraneous and nothing buried.

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

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

For a simple two-parameter status update with an output schema and full annotation coverage, the description supplies the action, allowed values, and auth need. It stops short of explaining mentionId semantics or error behavior, but those are minor given the tool's low 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 coverage is 0%, so the description must carry the parameter burden. It does enumerate the four valid status values (new, seen, irrelevant, done), which compensates for the missing status enum, but mentionId is left entirely unexplained 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 (set) and resource (a mention's status) with the exact target field, so an agent knows precisely what changes. It is clearly distinct in intent from read-only siblings like listMentions or watchMentions, though it never names or contrasts those alternatives.

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 only guidance is a prerequisite ('Needs a free SnoopScan key'). There is no when-to-use vs when-not, and no routing to listMentions/watchMentions for the read side of the same resource, leaving the agent to infer usage context entirely.

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 read-only/idempotent/non-destructive/open-world, so the description adds real value on top: the document-vs-page degradation behavior and the cost model ('billed per 10 document pages'). It does not mention rate limits, size ceilings, or how failure on an unparseable document is reported.

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: what it does, when to choose it, and the cost/edge-case. The primary behavior is front-loaded and 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?

An output schema exists, so return-value documentation is not required, and the safety profile is fully covered by annotations. The remaining gap is the undocumented maxChars truncation semantics, which an agent needs in order to size requests correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions 'maxChars' (default 20000) or what happens when the document exceeds it — a critical truncation behavior for a text-extraction tool. Only the 'url' parameter is implicitly explained, via 'a document at a URL'.

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 (read/parse) plus the resource (a document at a URL) and names the output format (text as markdown). It implicitly contrasts itself with page-oriented siblings via 'a link to a document rather than a web page', but never names 'scrape' or another 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?

Gives a clear selection rule: use this for document links, not web pages, and explains the fallback ('a URL that turns out to be an ordinary page is returned as that page'). It stops short of naming the alternative tool (e.g. scrape) for plain pages, so routing 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: results come from public search only, it does not sign in or read profile pages, and it explains the 'confirmed' vs 'former' person semantics. It stops short of describing rate limits or result shape specifics.

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 inputs, then return semantics and prerequisite. The role/seniority lists are dense but earn their space as the only source of allowed values. The confirmed/former paragraph is slightly wordy but conveys non-obvious semantics.

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 an output schema present, return values need not be spelled out, and the description still explains the meaningful return flags (confirmation/former) plus the auth prerequisite. For a 4-param read-only lookup this is complete enough to call correctly.

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

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

Schema coverage is 0% and no enums are defined in the schema, so the description compensates by enumerating the valid role and seniority values, which is genuinely useful. However it says nothing about the `limit` parameter (default 8) or the behavior of a null role/seniority, leaving one of four params unexplained.

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

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

States a specific verb+resource ('Find the people at a company') and clarifies the two filtering axes (what they do, seniority). An agent can tell it surfaces named people, but the description never differentiates it from close siblings like findContacts or findLeads, so routing depends on 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?

It gives the input shape ('give it a company and optionally a role and a seniority') and a prerequisite ('Needs a free SnoopScan key'), which is useful. But there is no when-to-use versus alternatives guidance, and the closest siblings (findContacts, findLeads) are never mentioned, leaving selection ambiguous.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive, so safety is covered without the description. The description adds the markdown output form, which is genuinely useful, but stays silent on notable behavior implied by defaults: a large `maxAge` cache window, `maxChars` truncation, and `waitFor` rendering delay.

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, no filler, with the core capability front-loaded ahead of the routing hint. Every sentence 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?

An output schema exists, so return values need no explanation, but the tool exposes six parameters with zero documented semantics and undisclosed caching/truncation behavior. For a 6-param tool with 0% schema coverage, the description should do substantially more than it does.

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 6 parameters, so the description carries the full burden and largely fails it. Only the `url` parameter is addressed implicitly ('a specific URL'); `maxAge`, `formats`, `waitFor`, `maxChars` and `onlyMainContent` are given no meaning at all, despite defaults that materially change output.

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

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

The description gives a specific verb and resource ('Fetch a single web page') plus the output form ('clean markdown'), which is more than a name restatement. It differentiates from the page-discovery tools, but does not draw any boundary against the closer sibling `parse`, leaving that distinction to inference.

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

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

It states a clear trigger ('when you have a specific URL and need to read what is on it') and names an alternative path ('use `search` or `map`') for the discovery case. One named alternative (`map`) is not in the sibling list, and no when-not condition against `parse` is offered, so it falls short of a full routing spec.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive behavior, so the safety profile is covered. The description adds genuinely new context: fetchContent is slower and incurs per-page billing, which is exactly the kind of cost/latency disclosure 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?

Two short sentences, front-loaded with the core action and return shape, then the optional cost-bearing behavior. No filler, though the line breaks make it slightly fragmented.

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?

An output schema exists so return values need not be explained. For a 4-parameter tool with zero schema coverage, though, the description leaves two parameters undocumented and does not address result limits or content truncation 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 burden, yet it only explains fetchContent's behavior. The limit and maxCharsPerResult parameters are left entirely unexplained in both schema and description, and query is trivially obvious.

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 ('Search the web') and specifies the return shape (title, URL, snippet). It does not differentiate itself from the sibling tools parse and scrape, but the core purpose is unambiguous.

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

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

The description explains the fetchContent option and flags it as slower and billed, which implies when to enable it. However, it gives no guidance on when to prefer search over the sibling tools parse or scrape, leaving that selection 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?

Goes well past the annotations: discloses the cost model (billed per results page and per detail fetched), an auth prerequisite (needs a free SnoopScan key), a hard cap (up to 20 a call), and that includeDetails toggles phone/website in the output. Annotations only cover the safety profile, so this adds real invocation-level context.

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 query example, then output, cost and alternative routing in tight sentences. No filler; every clause delivers actionable information.

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

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

With an output schema present, the description needn't detail return values, yet it usefully names the key fields. Cost and auth are covered. Minor gap: the accepted form of `location` (city string vs coordinates) is left inferential.

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 load: it explains query via the example, location via 'in "Leeds"', and includeDetails by naming what it adds. The limit parameter is only loosely covered ('up to 20 a call'), which does not clarify its default of 10 or its relationship to the cap.

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

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

States a specific verb (search) and resource (Google Maps businesses) and disambiguates from the sibling findLeads. The concrete example '"plumbers" in "Leeds"' makes the intended input shape immediately obvious to an agent.

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 routes the agent: use this for a Maps-style search, use `findLeads` when a whole list with emails, owners and several sources is needed. The selecting condition is stated, not implied.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: only public signed-out data, billing per call, no charge when no data returns, and the need for a free SnoopScan key. It does not discuss rate limits or error behavior, but it substantially improves behavioral clarity.

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 core purpose, followed by a concrete example, discovery guidance, and key operational caveats. Every sentence adds useful information without redundancy. The final key requirement is compactly stated.

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

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

Given that an output schema exists, the description need not explain return values. It covers the important invocation context: public data scope, billing, key requirement, and endpoint discovery via `socialEndpoints`. The main remaining gap is that valid platform and endpoint values are not summarized directly, though the pointer to `socialEndpoints` mitigates this.

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 compensate. It provides an example showing `platform`, `endpoint`, and a `params` object, and it points to `socialEndpoints` for valid inputs. However, it does not document valid platform values or endpoint-specific parameter meanings directly, leaving part of the parameter semantics delegated.

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 specifies that this tool returns structured social-platform data such as profiles, posts, videos, comments, transcripts, and search, and contrasts it with page-style scraping. It also points to the `socialEndpoints` sibling for endpoint discovery, which helps distinguish its role. The purpose is clear, though it is framed as a general dispatcher rather than a single fixed operation.

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 tells the agent to call `socialEndpoints` for the full endpoint list and each endpoint's inputs, and it states that only public signed-out data is available. It also notes billing and key requirements, which are useful invocation conditions. It does not explicitly compare this tool with other data-access siblings such as `search` or `scrape`, so it falls short of full when-to-use guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lower; the description still adds two things annotations don't carry: the calls are free and a free SnoopScan key is required. That auth/cost context is exactly the kind of added value expected. It stops short of describing pagination or result volume.

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 verb and resource, and no filler. The trailing whitespace and abrupt 'Free.' fragment are minor structural blemishes but the content is tight.

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

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

An output schema exists, so return-value detail is not required, and the description covers the auth prerequisite and cost. The only real gap is the ambiguous role of the `platform` parameter, which leaves an agent unsure how to use the sole input.

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 the single `platform` parameter is undocumented, so the description must compensate. It lists the available platform values (YouTube, TikTok, Instagram, X, LinkedIn, Facebook, Threads, Pinterest), which helps an agent pick a value, but never states whether the parameter filters the listing or whether omitting it returns all endpoints.

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 social endpoints') and explicitly scopes it to what the sibling `social` can call. It also enumerates the per-entry fields (platform, name, return value, inputs, price), so an agent knows exactly what this discovery tool yields versus the sibling that executes calls.

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 reference to `social` implies this is the discovery step before invoking an endpoint, but there is no explicit 'call this before social' instruction and no when-not guidance. Usage is inferable 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 readOnly/idempotent/non-destructive annotations, it discloses the 7-day lookback window, that 'nothing is saved', that every answered source query is billed to account usage, and that a free SnoopScan key is required. Those are exactly the operational facts (quota, auth, ephemerality) an agent needs before invoking a broad open-world scan.

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?

Core behaviour and the keyword-vs-watchId choice are front-loaded, which is good. But the source enumeration consumes most of the text, and the appreviews entry spills into a nine-service list with awkward line breaks — moderately justified since no parameter enums exist, but it reads as bloated rather than tight.

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

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

Return values need not be described because an output schema exists, and the description covers the essentials an agent needs: no persistence, quota consumption, auth requirement, and the 7-day window. The remaining gap is that it never says which sources run when `platforms` is omitted, nor what `exclude` and `competitors` do.

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 it only partly does: it explains `keywords`, `watchId`, defines `feeds` as RSS/Atom addresses, and ties `places` to Discourse forums, review pages and Telegram channels. `exclude`, `platforms` and `competitors` are never defined — `platforms` is only indirectly inferable from the source list, and `exclude` and `competitors` get no explanation 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?

States a specific verb and resource: run keywords against sources now and list what is found in the last 7 days, with nothing persisted. It also distinguishes itself from creating a watch ('try before creating a watch') and from running a saved watch ('watchId to run a saved one'), which lets an agent separate it from watchMentions and listMentions.

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 concrete when-to-use rule: pass `keywords` to preview before creating a watch, or `watchId` to re-run an existing one. It does not name the sibling tool to use for actually creating the watch, and it doesn't say when to prefer listMentions or watchMentions over this preview, so the routing is implied rather than fully 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?

Goes well beyond the annotations by disclosing the auth requirement ("Needs a free SnoopScan key") and a cost/quota side effect ("Each answered source query is recorded on the account's usage"), plus defaults for platforms and interval. The gap is update semantics: it never says whether passing `watchId` merges fields or replaces the whole watch, which matters for a non-idempotent write 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?

The action and both modes are reasonably front-loaded, but the opening enumerates eighteen source platforms in one breath and the rest is a single run-on paragraph mixing creation, per-parameter semantics, and cross-references. The platform list is largely duplicated later by the `platforms` enum, so it does not all earn 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?

An output schema exists and auth/quota are covered, but for a create-or-update mutation with 11 optional parameters the description omits partial-update semantics and the purpose of `active` and `webhook`. Those are real gaps for correct invocation, not cosmetic ones.

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 every parameter is nullable, so the description carries the full burden — and it does for 9 of 11 params, including enumerated platform names with a default, the 10-item caps on `feeds`/`places`, the meaning of `places` per source type, and the 5–10,080 interval range. `active` and `webhook` are never explained, leaving two 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?

Opens with a specific verb+resource ("Create a watch that looks for keywords ... on a schedule") and adds the classification behavior (bug report, complaint, question, buying intent, praise, competitor). It also distinguishes create vs. update mode via `name`+`keywords` versus `watchId`, which separates it from siblings like watchPages and listMentions.

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

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

Explicitly states both invocation modes ("Give `name` and `keywords` to create one, or `watchId` plus the fields to change") and routes to the correct alternatives: "Read results with `listMentions`; try keywords first with `testMentions`." That is a clear when-to-use-this vs. when-to-use-siblings statement.

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 declare the generic safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true). The description goes well beyond: a 50-page cap, the intervalMinutes range of 5-10,080, per-check billing ('Each check bills the pages it fetches'), and an authentication requirement ('Needs a free SnoopScan key') — cost and auth details an agent cannot get from structured fields.

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

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

Front-loaded with the core action and limit, followed by the interval range, billing, and sibling routing in tight sentences. The trailing 'Needs a free SnoopScan key.' reads as a dangling fragment rather than a structured prerequisite, but every sentence 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?

An output schema exists, so return values need no explanation, and the description covers scheduling, limits, cost, auth, and follow-up tools. The only real gap is the unexplained 'goal' parameter and no stated behavior for what happens on failure or how monitors are managed/deleted.

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 4 parameters, so the description must compensate. It does add real value for intervalMinutes (valid range 5-10,080 vs. the schema's bare default of 60) and indirectly caps urls at 50, but name and goal are never explained — notably 'goal' is a non-obvious parameter left entirely 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 ('Start a monitor that re-reads up to 50 pages on a schedule') plus the outcome ('records which are new, changed or failing'). It also names the sibling tools checkMonitor and listMonitors, so an agent can separate creating a monitor from reading or listing one.

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 routing: read the latest result with checkMonitor, list yours with listMonitors. It establishes context for the create/monitor workflow but never states when a monitor is preferable to one-off siblings like scrape or crawl, nor any exclusion conditions.

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