Website Contact & Social Extractor

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: robots-respecting, public hosts only, cost charged per page actually fetched with failed fetches free, and no URL logging. The only tension is that a tool that fetches arbitrary external URLs is labelled openWorldHint=false, which the description's 'GET the URL' quietly undercuts.

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, usage and cost are front-loaded and useful, but the long response enumeration (emails[], phones[], whatsapp[], social, addresses, organization, pages, summary, confidence, sources, version, warnings, disclaimer) is verbose and largely redundant when an output schema already exists — and it lists fields that don't obviously belong to a reachability check.

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, and it covers the operational essentials an agent needs: cost model, robots/public-host constraints, and privacy. It omits error and failure semantics — what a non-200 or unreachable host looks like in the response.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains the url parameter only via an example and gestures at respect_robots through 'robots-respecting', but never states what setting respect_robots to false would do, or what happens on a robots disallow. Partial compensation, not full.

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

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

The opening sentence names a specific verb (GET) and resource (the URL) and enumerates exactly what it returns: status, final URL after redirects, content type, title, languages, contact-page linkage. That is much sharper than the title alone. It never explicitly distinguishes itself from extract_contacts or find_social_profiles, and the later response block oddly lists emails/phones/whatsapp, which blurs whether this is also a contact extractor.

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 before a bulk job or to clean a URL list" gives concrete situations for calling it, and the example 'example.com' illustrates the input shape. It stops short of naming the alternative sibling tools or saying when NOT to call it (e.g. when you already have a URL list of failed fetches to re-run).

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

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

The description contributes substantial behavior beyond the annotations: per-page billing with failed fetches free, per-item provenance, and the privacy note 'URLs are not logged'. That is genuinely useful information an agent cannot get from readOnly/idempotent/destructive hints. Minor tension: it clearly reaches arbitrary external sites while openWorldHint is false, but the core safety hints align, so no hard contradiction is recorded.

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 useful, but the second half enumerates the entire response shape (emails[], phones[], social{}, addresses[], pages[], summary{}, data_confidence, estimated_items[], sources[], warnings[]...), which duplicates the output schema and pads the definition. A tighter definition would let the output schema carry that load.

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 a full output schema, rich annotations and complete parameter docs, the description is nearly complete for correct invocation: scope, cost model, privacy, and fetch behavior are all covered. The main omission is any explicit routing among sibling tools.

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 url, region, max_pages, include_social, respect_robots and follow_contact_pages are all documented in the schema. The description restates the max_pages semantics and region example without adding new meaning, so the baseline 3 applies.

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

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

Strong specific verb and resource: 'Fetch a site's homepage and up to max_pages-1 contact/about pages and return every email, phone...'. It clearly tells an agent this is a single-site contact scraper. It does not explicitly differentiate from siblings like extract_contacts_bulk, extract_from_html, or find_social_profiles (whose territory partially overlaps with the social{...} output), so it stops short of a 5.

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

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

Usage is implied by the detailed scope and an inline example ('url noahsarch.tech, max_pages 3, region AE') plus a caveat that respect_robots=false is only for owned sites. However there is no explicit 'use this when X, prefer sibling Y when Z' routing, so the agent must infer when to pick this over the bulk or HTML variants.

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 read-only and idempotent annotations, the description discloses important operational behavior: charging is per page fetched across all sites, failed fetches are free, and URLs are not logged. It also explains what pages are fetched and that the response includes warnings and a disclaimer, which materially helps an agent understand cost and privacy implications.

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 and example, but it is overly long and enumerates many response fields despite an output schema being present. Billing information is repeated in two separate places, which adds redundancy without new meaning.

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 bulk extraction tool with an output schema, the description covers the essential operational context: cost model, failed-fetch behavior, privacy, example inputs, and high-level result contents. It is only incomplete around sibling-tool selection guidance and the unexplained include_social parameter.

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

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

Schema coverage is 75%, with urls, region, and max_pages already documented in the schema; the description usefully reinforces these with an example and clarifies max_pages as homepage plus contact pages per site. However, include_social has an empty schema description and is not explained in the description, leaving one parameter 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?

The description clearly states that this tool extracts contacts from multiple websites in one call, with homepage and contact-page coverage. It is specific enough to distinguish a bulk lead-list operation, but it does not explicitly contrast itself with the single-site sibling tool extract_contacts.

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 lead-list framing and the example covering multiple URLs, max_pages, and region. However, the description does not explicitly say when to use this versus extract_contacts, extract_from_html, or find_social_profiles, nor does it state exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the description is free to add what annotations cannot: cost model, privacy ("URLs are not logged"), and the confidence/warnings/disclaimer envelope in the response. The pricing sentence appears copied from a fetching sibling and arguably contradicts the tool's own no-fetch premise, which blunts an otherwise strong disclosure.

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 well with the key differentiator, and the input example and cost note earn their place. However, the long comma-spliced enumeration of every response field (result, emails[], phones[], whatsapp[], social{}, addresses[], organization{}, pages[], summary{}, data_confidence, estimated_items[], sources[], data_version, warnings[], disclaimer) duplicates the output schema and makes for a wall of text.

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

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

For a 3-parameter, well-annotated tool with an output schema, the description covers purpose, input caveat, cost and privacy adequately. The only real gap is the internally inconsistent per-page charging language, which could lead an agent to avoid a free operation on cost grounds.

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 html, region and base_url are already fully documented with defaults and examples; baseline is 3. The description never mentions region (phone-number interpretation) or base_url (relative-link resolution), so it adds nothing over 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?

"Same parser, no fetching" plus an explicit enumeration of extracted data types (emails incl. obfuscated forms, phones, WhatsApp, social, addresses, schema.org org data, contact-page links) makes the verb and resource unambiguous. It implicitly contrasts with the fetching siblings (extract_contacts, check_url), so an agent can tell it doesn't touch the network 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?

"No fetching" and "You already have" (title) clearly establish the precondition for choosing this over extract_contacts. It lacks an explicit "use extract_contacts when you have a URL instead" routing sentence, and the later line "Charged per page actually fetched; failed fetches are free" muddies the when-to-use story for a tool that fetches nothing.

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 safety, and the description adds genuinely new behavioral facts: billing is per page actually fetched with failed fetches free, and URLs are not logged. Those cost and privacy disclosures materially change how an agent should invoke 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?

Front-loaded scope constraint, then platforms, then exclusions, example, response, cost. Every clause carries information. The response-field enumeration is a dense run-on that would read better as a structured list, costing a point.

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

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

Despite an output schema existing, the description adds cost model, privacy posture, failure behavior and scope limits — everything an agent needs to call this correctly. Nothing material is left unstated.

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

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

Schema coverage is 100% with a single url parameter, so the schema does the heavy lifting (baseline 3). The description earns an extra point by giving a concrete example value, 'https://example.com', which pins down expected URL format.

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

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

The description names a specific verb and resource (find social-media profiles) and enumerates the platforms covered, so an agent knows exactly what comes back. It also scopes to homepage-only. It stops short of stating how this differs from the overlapping sibling extract_contacts, which also returns emails/phones per the response description.

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?

'Homepage only' and 'Share buttons are excluded' give clear usage boundaries and a negative case. What's missing is any named alternative — an agent cannot tell from this text when to prefer extract_contacts or extract_contacts_bulk over this tool.

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