web-tools

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, yet the description adds genuinely new behavior: it runs a named Apify Actor on the caller's own account at pay-per-event $0.001/article and that failed URLs are not billed. It stops short of describing partial-failure behavior, latency, or whether per-URL results include error entries.

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 dense sentences: what comes back, the failure/billing caveat, then the execution and cost model. Return fields are front-loaded and every clause carries information an agent can act on.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields, and it discloses the cost and actor-execution model. It leaves gaps around error/partial-success semantics and the 25-URL batch ceiling, which matter for a multi-URL extraction call.

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

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

Schema description coverage is 100%, so all three parameters are already documented and the baseline of 3 applies. The description adds no guidance on maxChars truncation effects or when the apify_token fallback is needed, so it does not exceed the schema.

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

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

States a specific verb (extract) plus the exact resource and enumerates the returned fields: title, author, published date, body text, word count, content hash. That makes the output shape unambiguous, but it never contrasts itself with the closest sibling extract_website_content, so an agent must infer the article-vs-page distinction.

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

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

Usage is only implied by the parameter name articleUrls and the 'article' framing; there is no explicit statement of when to pick this over extract_website_content or extract_web_metadata, nor any note about non-article pages failing. The billing note is cost guidance rather than selection guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so safety is covered; the description adds genuinely new behavior: execution happens through a specific third-party Actor (skilled_glee/contact-details-extractor) on the caller's own Apify account, with pay-per-event billing. It also discloses a real limitation (North American phone numbers only), which prevents over-broad expectations.

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

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

Two dense sentences with zero filler: extraction scope first, execution and cost second. Nothing repeats the title or schema.

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

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

For a two-parameter, read-only tool with full schema coverage, the description covers what is extracted and the billing/account model. It does not say whether results are returned per-URL or aggregated, nor how partial failures are reported, and there is no output schema to fall back on — a minor but real gap.

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

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

Schema coverage is 100%, so pageUrls (1-25 URIs) and the optional apify_token fallback are already documented; the description adds no syntax, batching, or per-URL semantics beyond what the schema says. Baseline 3 applies since the schema carries the parameter burden.

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) and a precisely enumerated resource set (emails incl. mailto, North American phone numbers, LinkedIn/X/Facebook/Instagram/YouTube links, contact/about/team page links) from web pages. That enumeration cleanly separates it from siblings like extract_article, extract_web_metadata and extract_website_content without needing to name them.

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

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

Usage is only implied by the resource list; there is no explicit when-to-use/when-not or pointer to alternatives such as extract_website_content for broader scraping or verify_emails for validation. The billing note ($0.0015/page, charged to the user's own Apify account) is a useful cost signal that helps an agent decide, but it is not routing guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and the description adds material facts the annotations lack: the tool runs a specific Apify Actor on the caller's own Apify account with pay-per-event pricing at $0.001/page, billed by Apify. It stops short of describing failure behavior for unreachable pages or the 25-URL cap.

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

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

Two sentences, zero filler: the first front-loads the returned fields and format, the second front-loads execution location and cost. 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?

With no output schema, the description compensates by listing the returned fields, and it covers billing and account context. Sibling differentiation and error/failure behavior are the remaining gaps, but for a simple two-parameter read tool this is close to sufficient.

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

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

Schema coverage is 100%, so both pageUrls and apify_token are fully documented in the schema, and the description adds nothing about URL format, batching, or when the token fallback is needed. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

It uses a specific verb and resource and enumerates exactly what is extracted (title, meta description, OG, Twitter Card, JSON-LD, canonical URL, language, H1s), which clearly separates it from siblings that pull article bodies (extract_article) or full page content (extract_website_content). An agent can choose it without opening the schema.

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

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

The description implies usage (extract metadata from web pages) but never states when to prefer it over extract_website_content or extract_article, nor any exclusions such as non-HTML URLs. Usage must be inferred from the listed output fields.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: deterministic extraction with no AI/browser, boilerplate stripping, execution on the user's Apify account, and pay-per-event billing at $0.002646/page.

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 two tight sentences with zero waste. The core capability is front-loaded, followed by distinguishing operational details (deterministic, no AI/browser, pricing).

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by naming clean text, title, description, word count, and language. It also covers cost and execution environment, making it largely complete for an agent deciding whether and how to call it.

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

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

Schema description coverage is 100%, so all three parameters—including pageUrls, maxChars, and apify_token—are already documented in the schema. The description adds no parameter-specific syntax or constraints, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource ('Fetch web pages and return clean readable text') and lists concrete outputs (title, description, word count, language). It is clear what the tool does, but it does not explicitly differentiate itself from siblings like extract_article or extract_web_metadata.

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 implies usage through context—'Deterministic, no AI, no browser' and per-page pricing—but never states when to choose this over extract_article, extract_web_metadata, or probe_urls. There are no explicit exclusions or alternative recommendations.

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 billing model (pay-per-event $0.0004/URL, billed by Apify) and that it runs on the caller's own Apify account — material facts an agent cannot get from readOnlyHint/idempotentHint. It also notes the fallback apify_token path for clients that can't send auth headers.

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: capability and return fields first, the body-read exclusion second, cost/account third. No padding, and the most decision-relevant information is front-loaded.

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?

Without an output schema, the description does the work of explaining return fields, and the annotations already cover safety. What's missing is failure semantics (what happens on timeouts, DNS errors, or non-2xx) and the 25-URL batch limit, which matter for a network probe.

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 only 40% schema description coverage, the description does fill some gaps by implying method (HEAD vs GET) and redirect handling, but it never mentions the 25-URL cap, the timeoutSecs/timeout behavior, or the semantics of followRedirects=false. Two documented parameters plus visible enum/defaults carry most of the weight.

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 (probe/check URLs) and enumerates exactly what is returned: HTTP status, final URL after redirects, redirect count, Content-Type, timing. The sentence 'No page body is read' cleanly separates it from the sibling extract_* tools that fetch content.

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

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

The scope statement implies when this is the right pick (link validation, redirect/header inspection rather than content extraction), but no sibling is named and there is no explicit 'use X instead when...' guidance. The agent must infer the boundary from the phrase 'No page body is read.'

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 the description adds real context beyond them: the underlying Actor (skilled_glee/email-verifier), that it runs on the caller's own Apify account, and pay-per-event pricing at $0.001/email billed by Apify. It also discloses the return shape (pass/risky/fail plus reason codes) despite having no output schema.

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

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

Two dense sentences, front-loaded with the core action and its checks, then the execution/cost model. Every clause carries information an agent needs; nothing is repeated from the annotations or schema.

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

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

For a two-param batch verification tool with no output schema, the description covers what is checked, what the verdict looks like, cost, billing party, and which account executes it — everything needed to call it correctly and safely.

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

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

Schema description coverage is 100%, with both params documented in-schema including the max-100 batch limit and the token fallback for clients that cannot send auth headers. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Check email addresses without sending mail') and enumerates exactly what is checked: syntax, MX, null MX, disposable domains, role accounts, free providers, typos, plus the pass/risky/fail verdict and reason codes. That resource is unmistakably distinct from the sibling extract_*/probe_urls tools, so an agent can route on it without opening the schema.

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

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

Usage context is clear (verifying a list of email addresses) and the boundary 'without sending mail' rules out a plausible misreading. However, no explicit when-to-use vs. alternatives or exclusions are given — though no sibling competes for this task, so the omission is low-cost.

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