agentsvc.io

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

Beyond the annotations, the description discloses that audio is deleted after the call, that processing runs on agentsvc.io with Whisper, the size/duration limits, the x402 payment path and price, and the return shape. These are meaningful behavioral details an agent needs before invoking 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?

The description is front-loaded with what the tool does and the key limits, and most sentences carry useful information. It is dense and includes some promotional/endpoint detail that could be trimmed, but it remains readable and purposeful.

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

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

There is no output schema, so the description correctly explains the return values: text, detected language, duration, and timestamped segments. It also covers limits, payment behavior, sample input, and the alternative endpoint, making it complete for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful constraints not present in the schema: supported audio formats, 10-minute and 24 MB limits, and the base-vs-small speed/accuracy tradeoff. It stops short of explaining edge cases around base64 vs URL priority.

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+resource ('Audio transcription and speech to text') and enumerates concrete audio sources such as voice notes, meetings, podcasts, and calls. It is clearly distinguishable from siblings like translate and web_scrape.

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 context for when the tool applies, including supported formats and a free sample call, and notes an OpenAI-compatible alternative endpoint. It does not explicitly compare against the translate sibling or state when not to use it, so it stops short of full routing guidance.

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

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

Beyond the annotations, it discloses the paid nature of the call, a concrete price range ($0.0015 to $0.6 USDC), the payment rail (x402, USDC on Base/Solana/Polygon/Arbitrum), and that x402-capable MCP clients settle automatically. It also notes the example input is a free sample, which is operationally important context an agent cannot get from the schema or the hints.

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

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

It is front-loaded with the invocation example, then the prerequisite, then cost mechanics — a sensible order with little filler. The payment sentence is dense but each clause (price, chain, auto-pay) carries distinct information an agent needs before committing funds.

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 nested-input dispatcher with no output schema, the definition covers invocation, prerequisites, and cost/auth requirements thoroughly. It never indicates what a successful response looks like or how errors and payment failures surface, which is the main remaining gap.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it shows the exact JSON shape, ties 'service' to find_service output, and ties 'input' to that service's own input_schema. That resolves the nested-object ambiguity the schema alone only gestures at.

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 ("Run any agentsvc.io service by name with its input") and backs it with a concrete payload example, so the dispatcher nature is unambiguous. It is clearly separable from find_service, which is positioned as the discovery step rather than the execution step.

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

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

It gives an explicit prerequisite: "Use find_service first to get the name and input schema," which tells the agent the correct call order. It does not say when to prefer a sibling direct-call tool (e.g. web_scrape, translate) over this generic dispatcher, leaving that choice 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?

Adds substantial context beyond the annotations: no email is actually sent, checks include syntax/MX/disposable/role, results are cached 6 hours, and the call costs $0.002 USDC via x402 with named supported chains. The payment and caching traits are exactly the kind of behavior annotations cannot convey.

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

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

Front-loads the core purpose, mechanism, and return statuses before pricing. Every sentence carries information, though the pricing/x402 sentence is dense and slightly long; still no wasted content for a paid tool.

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

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

With no output schema, the description compensates by enumerating all five status values and noting the raw SMTP reply. For a single-parameter tool, nothing an agent needs in order to call and interpret it is missing.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline is already met. The description additionally marks it required and supplies a concrete example input ('{"email":"support@microsoft.com"}'), which clarifies the expected format beyond the schema.

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

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

States a specific verb and resource ('checks whether an email address really exists') and explains the mechanism (SMTP RCPT TO probe). No sibling overlaps, so an agent can select it unambiguously from the listed tools.

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

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

Gives three concrete use contexts: before sending outreach, cleaning lead lists, blocking fake sign-ups. There are no competing alternatives among siblings, so no exclusions are needed, but it stops short of stating when not to use it (e.g., bulk volumes, privacy-sensitive cases).

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, destructiveHint=false and openWorldHint=false. The description goes beyond that by disclosing the cost model ("Free") and the shape of the returned payload (price, input schema, a free example input), which is genuinely useful since there is no output schema. It does not mention rate limits or result pagination.

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 most decision-relevant fact ("Free") and then the capability, the return shape, and the follow-up action. No sentence is filler and the workflow is readable in one pass.

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

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

With no output schema, the description does the work of describing returns (price, input schema, sample input), and annotations carry the safety profile. The only real gap is the undocumented limit parameter and the absence of any note on result ranking or result count. Everything an agent needs to make the call is otherwise present.

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

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

Schema coverage is only 50%: query is documented as "What you need, in a few words" while limit carries only default/min/max bounds and no prose. The description compensates by giving four concrete query phrasings that show the expected granularity. The limit parameter's purpose (result count) is still left to the schema bounds.

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) plus the resource (all 127 agentsvc.io services) and the axis of search (by task), with concrete query examples. It also positions itself against siblings by naming call_service as the downstream step, so an agent can tell it apart from the concrete task tools like audio_transcribe or token_verdict.

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 clearly establishes the use context: discover a service here, then invoke it with call_service. That routing is explicit. It stops short of stating when NOT to use it (e.g. when the exact service tool is already known), so it is clear context without full 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?

Goes well past the readOnly/openWorld annotations by disclosing the local-database source (no third-party call), millisecond latency, address-class rejection behavior, the $0.0055 USDC per-call price with the x402 payment rails, and a free sample input. An agent knows exactly what it will cost and how payment is handled before invoking.

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

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

Front-loaded with purpose and return fields, and the pricing/licensing detail is genuinely decision-relevant for an agent paying per call. It is a single dense paragraph with heavy parenthetical stacking (payment rails, attribution), which costs it a point versus a cleanly segmented version.

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

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

With no output schema, the description compensates by enumerating the returned fields (country, region, city, lat/lon, timezone, ASN/org, is_eu). Payment mechanics, latency, and validation behavior are all covered, so nothing needed to call it correctly is missing.

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

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

Schema coverage is already 100%, so the schema documents the ip format. The description nonetheless adds meaning beyond it: the parameter defaults to the caller's IP, and invalid/private/reserved values are rejected rather than returning nulls. Minor tension with the schema marking ip required, but the added semantics are real.

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 ("IP lookup and geolocation: resolve any public IPv4 or IPv6 address to location and network data") and enumerates the returned fields. This clearly separates it from address-oriented siblings like geocode or postal_code and from dns_lookup.

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?

Explicit use cases are given: fraud and bot checks, geo-routing, analytics, tagging traffic, plus the boundary rule that invalid/private/reserved addresses are rejected. It lacks an explicit "use X instead" comparison to the nearest sibling (geocode), 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 readOnly/openWorld/non-destructive, but the description goes well beyond: data provenance, 7-day window, 15-minute refresh cadence, and critically the payment model ($0.0065 USDC via x402 on four chains, auto-paid by x402 clients) plus a free sample call. Pricing and auth are exactly the kind of context the agent cannot infer elsewhere.

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

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

Front-loaded with purpose, then alternatives, then params, then price — a logical funnel with no filler sentences. The parenthetical provenance stack is dense but each element (source, size, freshness, refresh rate) is decision-relevant.

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

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

No output schema exists, yet the description enumerates the returned fields, defines corpus boundaries and recency, and covers cost and payment mechanics. An agent has everything needed to decide and 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 100%, so the baseline is 3; the description adds real meaning on top — limit cap of 30 and the non-obvious category behavior ('tech' puts Hacker News first, others narrow the GDELT topic). Only the query syntax stays entirely with the schema example.

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 ('news search: latest news articles and headlines by keyword') and immediately scopes the corpus: ~100k English articles/day from GDELT plus Hacker News, last 7 days. Returned fields (title, url, source, published_at) are named, so the agent knows exactly what it gets.

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?

Explicit routing rules: 'Use for current events and topic monitoring', with named alternatives — crypto-news for crypto, discussion-search for sentiment, web-read-batch for full text. The when-not cases are 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 the safety profile (readOnly/openWorld/non-destructive), and the description goes well beyond them by disclosing the cost ($0.013 USDC per call), the payment rail (x402 on Base/Solana/Polygon/Arbitrum), and that compatible clients pay automatically. This is exactly the kind of cost/auth context an agent needs before invoking a paid 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?

Front-loads the purpose, then layers in use cases, params, pricing, and a sample. The param clause is dense, but given the low schema coverage that density is earned rather than wasteful.

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 nine-parameter tool with no output schema and near-zero schema descriptions, the definition covers every parameter, the return format (base64 JPEG), imagery characteristics, cost, and payment mechanics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 11%, but the description compensates thoroughly: it documents the place format, bbox ordering '[min_lat, min_lon, max_lat, max_lon]', the lat+lon+radius_km combination with range (5-500, default 50), date format and default (yesterday), layer options with default, and width/height ranges. All nine parameters are effectively 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+resource ('Daily true-color satellite image of any area from NASA GIBS'), names the source and resolution, and names the sensor families (MODIS Terra/Aqua, VIIRS). An agent can immediately distinguish this from siblings like weather, geocode, or satellite_compare.

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

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

Gives concrete usage scenarios ('see clouds, smoke, snow, floods or fires on a given day') and points to a free sample input for testing. It lacks explicit when-not guidance or routing to the sibling satellite_compare, so it stops short of full alternative disambiguation.

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, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the $0.0025 USDC per-call price, the x402 payment path (USDC on Base/Solana/Polygon/Arbitrum), automatic payment for x402 clients, and a free sample call. It omits any note on rate limits or result-shape/pagination behavior, 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?

Front-loaded with purpose, then params, then pricing and the free-sample input, so the reader gets the essentials first. It is dense and slightly run-on in a single paragraph, but nearly every clause (form list, financial field list, payment rails, sample call) carries information an agent needs.

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

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

No output schema exists, so the description carries the burden of describing return values, and it does so explicitly (profile, filings with direct document links, financials with named line items). Payment and a sample invocation are also covered. It is complete enough to call correctly; the only gaps are rate limits and result pagination/shape detail.

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 60% schema description coverage, the description compensates well: it clarifies that ticker or cik is 'one required' (the schema itself marks zero required params, which is a real gap the description fixes), gives a forms filter example (['10-K','8-K']), and restates the limit range (1-50, default 10) and include_financials default. This adds genuine semantics beyond the schema, though it does not explain form-type conventions or CIK 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?

States a specific resource (SEC EDGAR US public company data) and enumerates exactly what comes back: company profile, recent filings by form type with document links, and optional annual financials with named fields. This is far more specific than a generic 'company data' tool. It does not, however, explicitly differentiate itself from siblings like company_brief, company_enrich, or company_lookup, which could plausibly overlap.

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 content scope ('US public company data from SEC EDGAR') and the free-sample example input, which shows a concrete call shape. There is no explicit when-to-use/when-not-to-use guidance and no alternative tool is named, so an agent must infer that this is the filings-specific option versus the other company_* siblings.

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

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

Annotations only cover the read-only/safe profile, but the description adds material behavior: per-call pricing ($0.009 USDC via x402), accepted payment chains, auto-payment behavior for x402 clients, and a grading rule ('Young or illiquid tokens can never grade above C'). Payment and grading constraints are exactly the kind of context annotations cannot express.

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

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

The purpose and result shape are front-loaded and the length is defensible for a tool with payment semantics, an unusual grading rule, and no output schema. It is somewhat dense/run-on with minor repetition (mint/freeze/owner powers restated), but no sentence is truly wasted.

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

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

With no output schema, the description carries the return-value burden and does so fully: grade, label, score, reason, share_url, share_text, and key facts. Combined with supported chains, parameter aliases, pricing, and a runnable example, an agent has everything needed to call it correctly.

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

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

Schema coverage is 67% (both token fields documented, chain not). The description adds value beyond the schema by noting 'solana auto-detected' and confirming the tokenAddress alias, plus the accepted address formats. The chain default is already in the schema, so this is a modest increment rather than full compensation.

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 states a specific verb and resource: 'Instant buy-or-avoid verdict for a token,' and then concretely enumerates what comes back (grade A-F, label, 0-100 score, reason, shareable page). It also names every supported chain and both input forms, so an agent understands exactly what this produces versus generic siblings like token_security.

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?

Context for use is clear (a fast pass/fail risk call before buying) and the free-sample example shows exactly how to invoke it. However, it never names or contrasts the many competing siblings (token_security, token_precheck, token_simulate, token_ai_verdict), so the agent is left to infer when to prefer this over them.

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 privacy (own Argos Translate server, no third party), the truncation behavior for long text, the English-pivot fallback for indirect pairs, and the pricing/payment mechanics ($0.009 USDC per call via x402 on four chains). This is exactly the extra context annotations can't carry.

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 supported languages, then layers privacy, limits, routing, price, and a runnable sample. Dense but every clause carries operative information; the language enumeration is long but necessary for correct target_lang selection.

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 stateless translation call with no output schema, the description covers inputs, limits, fallback behavior, payment requirements, and provides a free-sample invocation. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents text, source_lang, and target_lang. The description adds the max-length constraint and auto-detect default (both already in the schema) and mentions 'confidence' even though no such parameter exists in the schema, adding little clear value over structured fields.

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 precise verb+resource ('Translate text between 21 languages'), enumerates the supported language codes, and is clearly distinguishable from neighbors like language_detect or tts. An agent knows exactly what this does and its scope 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?

Explains operating context well: 1000-char limit, source_lang auto-detect default, and that indirect pairs route through English. It doesn't explicitly name an alternative tool (e.g., language_detect for detection-only) or state when-not-to-use, so it stops short of full routing guidance.

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

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

Annotations only declare read-only/open-world/no-destruction, but the description adds substantial behavior beyond that: the $0.0015 USDC per-call price paid in-band via x402 on four chains, the automatic payment path for x402 MCP clients, the fact that Markdown/plain-text files like llms.txt pass through unchanged, and that render:true silently switches output to plain text and is slower. These are exactly the non-obvious traits an agent needs before calling.

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 structure is well front-loaded: capability, default scope, return shape, then routing, then params and pricing. It is dense but mostly earns its length; the free-sample call and the example input are marginally promotional and the param list partly repeats the schema, which keeps it from a 5.

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

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

For a single-URL fetch tool with no output schema, the description covers everything material: what comes back, how truncation and links work, the JS-rendering escape hatch, the payment mechanism and cost, and which sibling handles other cardinalities. An agent can select and invoke this correctly without further inference.

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% and each parameter is already documented, so the baseline is 3. The description still adds value by restating the operative defaults and ceiling (max_chars default 8000, max 60000) and by explaining the output-format consequence of render, which the schema only hints at. It doesn't add much on include_links or URL validity rules beyond the schema.

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

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

The description states a specific verb and resource ('read any web page (URL) as clean, LLM-ready Markdown') and specifies what is returned: title, meta description, main content with headings, lists and links. It also carves out a distinct niche against siblings by declaring itself the 'Default tool for reading ONE web page', which separates it from web_scrape_batch and web-read-batch.

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 explicit routing rules: this tool for exactly one URL, web-read-batch for 2–5 URLs, web-scrape-batch for 6–20 (with the 'one payment' note), site-crawl for a whole site, and search-read when there's a question but no URL. It also prescribes the fallback path when a JS app returns nearly empty (set render:true or use webpage-reader), so both the when and the when-not are covered.

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 readOnly/openWorld/destructive hints. The description adds substantial non-obvious behavior: per-call pricing ($0.05 USDC), x402 in-call payment across four chains, partial-failure semantics ('A failed page is reported with its error while the others still return'), billing conditional on at least one page read, parallel fetching, and URL dedup. This is exactly the context annotations cannot carry.

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 capability and scoping, then pricing/alternatives/sample. It is long, but each block (when-to-use, failure behavior, alternatives, price, free sample) carries distinct decision-relevant information rather than filler. The embedded sample input is borderline verbose but operationally useful for a paid tool.

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

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

No output schema exists, and the description compensates by describing the return shape (Markdown per page with title and meta description, optional links), failure reporting, and billing outcome. Combined with the named alternatives, an agent has everything needed to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including ranges and defaults. The description largely restates them ('urls (1 to 20, required), max_chars per page (500 to 30000, default 8000), include_links') without adding format or edge-case detail. Baseline 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?

States a specific verb+resource+scope ('Bulk web scraper: read up to 20 web pages... each as clean, LLM-ready Markdown with title and meta description'). It explicitly distinguishes itself from siblings web-scrape (single URL) and site-map (find URLs), so an agent can route without opening 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?

Gives an explicit when-to-use ('Use when your agent works through a list of URLs (search results, product pages, a sitemap, a link list)') plus named alternatives with conditions ('For a single URL use web-scrape, to find the URLs of one site first use site-map'). Nothing 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.