CrawlForge MCP Server

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial non-obvious behavior: maxSteps<=10, maxUrls<=20, 120s wall-clock, pro confirmation, degraded output without LLM keys/Ollama, stealth retry rules, evidence marking, and credit cost. This goes well beyond structured 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, then alternates and exclusions, then hard limits, degradation behavior, stealth behavior, cost, and an example. Despite covering many operational details, every sentence carries actionable information and there is no filler.

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

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

For a complex autonomous research tool with no output schema but rich annotations and 100% schema coverage, the description supplies routing rules, runtime limits, cost model, fallback behavior, structured-output option, and a usage example. An agent has enough context to select and 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 100%, so the baseline is 3, but the description adds real semantic detail beyond the schema: 'model:"pro" uses deep multi-source research,' the hard limits for maxSteps and maxUrls, the 120s wall-clock constraint, and a concrete call example. It does not add much beyond the schema for prompt/schema/urls individually, but the model and limit context is useful.

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-and-resource purpose: an autonomous agent that researches, navigates, and synthesises an answer from the web without requiring URLs. It explicitly distinguishes itself from sibling tools by ruling out 'a URL you already have (scrape)' and 'a question one search answers (search_web)'.

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?

Provides explicit when-to-use guidance ('Use this when you need an autonomous agent...') and when-not-to-use alternatives, naming scrape and search_web directly. Also clarifies model:'pro' behavior, confirmation behavior, and cost/limit conditions that affect invocation choice.

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 provide readOnly/idempotent/non-destructive hints, so the description's burden is lower. It adds useful behavioral context beyond annotations: the 3-credit cost and the constraint that it accepts inline text rather than a URL. It does not describe the output structure, but the listed metrics partially imply what will be returned.

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 dense but every sentence earns its place: when to use, what it analyzes, input format, exclusion, cost, and a concrete usage example. It is front-loaded with the core purpose and ends with the example, which is ideal.

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 read-only, idempotent analysis tool, the description covers the key operational details: input expectations, cost, example invocation, and exclusionary context. The main gap is the lack of an explicit return-shape statement, but the absence of an output schema is partially mitigated by the listed analysis metrics.

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 text described as 'The text content to analyze'. The description adds concrete meaning by showing example option keys (extractTopics, includeSentiment) and clarifying that text is the raw content, not a URL. This compensates for the empty options object in the schema.

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

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

The description clearly states the tool analyzes text with NLP metrics (language detection, sentiment, topic extraction, entity recognition, readability) for content auditing and classification. It explicitly distinguishes itself from page-reading tools by saying 'Takes text, not a URL', separating it from scrape and related siblings.

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

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

It gives explicit when-to-use guidance ('NLP metrics on text you already hold') and when-not-to-use guidance ('Not for reading a page'), even naming the exact alternative path: 'scrape returns the markdown to pass in'. This provides actionable routing to the agent.

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, and non-destructive. The description adds real context beyond that: cost (5 credits), the sync-vs-async behavioral split with a URL-count threshold, and the async follow-up step via get_batch_results. It omits behavioral notes on pagination, redaction, and the robots.txt warning, which the schema carries instead.

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 primary action and scope, then routing, then mode mechanics, then cost and example. Every sentence carries distinct information 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?

For a 15-parameter tool with no output schema, it covers the critical decision path: batch scope, mode choice, async retrieval, cost, and alternatives. It leaves advanced parameters (redaction, robots, concurrency, pagination) to the schema, which is reasonable given 100% schema coverage, but a brief note on the async result-retrieval handle would round it out.

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 still adds value the schema doesn't: the ~25-URL practical threshold for sync mode and the cost figure. The worked example (urls, formats, maxConcurrency) illustrates expected shape. Marginal lift above baseline.

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) and resource (2-50 URLs in one call), scoping the batch use case precisely. It explicitly distinguishes itself from siblings: 'Not for one URL (scrape) or for discovering URLs (map_site).' An agent can select it without opening any schema.

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

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

Gives explicit when-to-use (2-50 URLs, 'Never loop scrape over a URL list'), when-not (single URL, discovery), and mode-selection criteria ('sync returns results directly for up to ~25 URLs; async with a webhook for larger batches, then get_batch_results'). Alternatives are named and conditions that select them are clear.

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 (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses non-obvious behavior: sessions expire 600s after open or 300s after last use, navigation invalidates refs so you must snapshot again, robots.txt is respected on every navigation, screenshots are stored as crawlforge:// resources, and per-operation credit costs. This is substantial disclosure the 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?

Despite covering seven operations and 21 parameters, the description is front-loaded with the core loop and the exclusion rule, then layers in cost, expiry, and a worked example. Every sentence is load-bearing — no filler restating the name 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 stateful, multi-operation, open-world tool with no output schema, it covers the lifecycle (open→snapshot→act→read→close), TTL constraints, ref invalidation, robots.txt handling, output-handle behavior (via schema), and cost. Nothing an agent needs to drive 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 baseline is 3, but the description adds meaning the schema can't: it groups parameters by operation (open takes url/stealth/engine/ttl/activity_ttl/viewport; read takes formats with onlyMainContent behavior), explains the @e1 ref targeting model, and notes refs include shadow-root and iframe elements. That is real value beyond the 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?

The description states a specific verb+resource (drive a browser across several calls, keeping page/cookies/login) and enumerates the exact operation set (open, snapshot, act, read, screenshot, close, list). It explicitly distinguishes itself from the two siblings it could be confused with — scrape for pages that need no interaction and scrape_with_actions for a pre-writable chain.

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 when-to-use ('look before each step instead of committing to a whole chain') and when-not-to-use ('Not for a page that renders without interaction (scrape), and not for an interaction you can write out in advance - that is one scrape_with_actions call'), naming the alternatives and the selecting condition. The one-call-vs-whole-chain cost framing makes the tradeoff concrete.

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, destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the credit cost model (4 credits base, scaling with page count) and the relative cheapness of map_site. It does not discuss crawling rate limits, politeness delays, or partial-failure behavior, which would push it to a 5.

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

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

Two tight sentences plus a compact example call. The alternative routing is front-loaded and every clause earns its place; no filler or restatement of the tool name.

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

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

For a 17-param crawling tool with an output schema and rich annotations, the description covers purpose, alternatives, and cost, which is the core decision surface. It omits guidance on budget-related knobs (max_inline_chars/result_handle flow, redact_pii) and session/login workflows, so it is not fully complete despite the strong 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 100%, so the schema already documents all 17 parameters. The description only illustrates three params (url, max_depth, max_pages, extract_content) inside an example, adding no semantic detail beyond what the schema carries. Baseline 3 for full schema coverage.

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 with scope ('fetch many pages of one site by following links') and gives concrete use cases (knowledge base, docs index, full-site audit). It explicitly names sibling tools it is not (scrape, batch_scrape, map_site), so an agent can disambiguate 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?

Explicit when-to-use and when-not-to-use with named alternatives routed by condition: single page -> scrape, known URL list -> batch_scrape, discovery alone -> map_site. It even flags map_site as cheaper, giving a cost-based tie-breaker.

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/openWorld annotations, it discloses that results are stored at crawlforge://research/{sessionId}, that maxUrls > 50 triggers a confirmation/elicitation step, that cost is 10 credits base and grows with maxUrls, and that synthesis depends on LLM keys or Ollama being configured. These details go well beyond what the annotations provide, and there is no contradiction.

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

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

The description is dense but composed of only a few high-value sentences: purpose, routing, exclusions, behavioral notes, cost, and an example. Every sentence earns its place, and the core purpose is front-loaded before alternatives and cost details.

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 20-parameter tool with no output schema, it covers essential context: choice criteria, execution pipeline, confirmation behavior, cost, storage location, and LLM configuration dependency. It does not explicitly describe the report's return shape, but the schema's max_inline_chars documentation about preview plus result_handle partially fills that 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 the baseline is 3; the description adds meaningful semantics around maxUrls (confirmation threshold and cost scaling) and includes a concrete example mapping topic, maxUrls, and researchApproach. Other parameters are left to the schema, but the schema already documents them thoroughly.

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

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

The description opens with a specific verb-resource pair ('exhaustive multi-source research on a topic') and details the pipeline: web search, source fetch/analysis, conflict detection, and report synthesis when LLM/Ollama is configured. It also explicitly differentiates this tool from search_web and scrape, so an agent can distinguish it from relevant siblings.

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

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

It states when to use it ('any report or comparison built from several sources'), names alternatives explicitly (search_web and scrape), and gives clear negative guidance ('Not for a question one search answers' or 'a single page'). It also declares it preferred over built-in deep-research skills, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context beyond that: the 2-credit cost, the fact that it returns clean markdown, and the overlap with scrape's default behavior. It doesn't cover response format or pagination, but the safety profile is handled 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?

Every sentence earns its place: purpose, exclusions with alternatives, cost, and example. The most critical information (what it is and when not to use it) is front-loaded. No filler or repetition.

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 tool with 6 parameters and nested objects, the description covers the core decision (when to use), cost, and a minimal invocation example. Advanced parameters like options, redact_pii, and max_inline_chars are left to the schema, which documents them thoroughly. The description is complete enough for correct basic invocation and tool selection.

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 baseline is 3. The description includes a concrete example using the required url parameter, which reinforces its meaning, but it doesn't add semantic detail for the other parameters beyond what the schema already provides. The example is useful but not additive to the schema's own 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 verb (extract) and resource (readable body of an article-style page with boilerplate removed). Distinguishes itself from siblings by explicitly naming scrape and fetch_url as alternatives for different scenarios, so an agent can tell them apart.

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?

Provides explicit when-to-use (RAG, summarization, LLM context) and when-not-to-use (JS-rendered pages, after fetch_url) with named alternatives. Also notes that scrape with onlyMainContent:true already returns the same clean markdown, eliminating redundant calls.

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 the read-only/idempotent/no-destruction profile, and the description still adds substantial behavior beyond them: exact cost (2 credits), the projected-vs-charged escalation pricing (7 projected, 2 charged when the plain fetch worked), the conditions that trigger escalation and the ones that never do (404/5xx), and the over-max_inline_chars fallback to a preview plus result_handle read via read_result. This is the kind of 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?

The routing sentence is correctly front-loaded, but the body is a single dense paragraph of nested parentheticals that restates much of what the 100%-covered schema already documents (path, keys_only, find, escalate). Information-dense rather than wasteful, yet harder to scan than it needs to be for a tool with 11 parameters.

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-shape burden and does so: it describes the data_rows index, the matches/matches_total/matches_truncated shape of find, the keys/type listing of keys_only, and the preview + result_handle contract for oversized results. Combined with the annotation-covered safety profile and full schema coverage, 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 100%, so the baseline is 3. The description goes beyond the schema by explaining how the parameters interact and what workflow they enable: find returns match paths 'ready to pass back as path', keys_only is for cheap key discovery before choosing a path, and the example shows a real path expression. It duplicates several schema details, but the combined-usage guidance is genuinely additive.

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 (extract a page's embedded JavaScript state) and enumerates the concrete framework payloads it targets (__NEXT_DATA__, __NUXT_DATA__, SvelteKit, Apollo, Redux, ytInitialData, Shopify, JSON script blocks). It also explicitly distinguishes itself from the sibling `scrape` for rendered HTML, so an agent can route 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?

The opening clause gives the exact selection condition (a page whose data lives in embedded state rather than rendered HTML) and the closing sentence gives both exclusions: 'Not for the rendered text of a page (scrape) or for sites built without a framework payload.' It also prescribes the escalation workflow (set escalate:true only when the site is known to block) and the discovery-first pattern (keys_only before choosing a path).

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), yet the description adds substantial operational detail: escalate runs the plain fetch first and only re-reads in the stealth browser if walled, projected 6 vs charged 1, a fixed 1-credit cost, PDF/binary refusal, and an empty client-rendered shell returning rendered:false with a warning. This is well beyond what the annotations provide and consistent with them.

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 behavior, then cost, then an example — a logical progression with no filler sentences. It is dense and somewhat long, but every clause carries operational information an agent would otherwise have to infer.

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

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

With no output schema, the description still explains return behavior: inline result vs preview plus result_handle, rendered:false with a warning on empty shells, and warning-recording when robots is disabled. For an 8-parameter, multi-mode tool, 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 url, escalate, filter_external, and the rest, setting the baseline at 3. The description still adds usable context by tying filter_external to its intent (dropping internal links) and naming the escalate trigger in plain language, though it largely restates rather than extends the schema's own parameter prose.

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 ('list the hyperlinks on one page') and immediately frames the concrete use cases (crawl seed list, broken-link audit, related resources). It explicitly distinguishes itself from map_site, scrape, and process_document, so an agent can route without opening any schema.

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

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

States both when-not conditions ('Not for a whole site (map_site)', 'not alongside a scrape of the same URL') and names the alternative that handles each case. It also gives the escalation trigger ('when the site is known to block') and the no-escalation cases (404/5xx), which is exactly the when-to-use guidance an agent needs.

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

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

Annotations already carry readOnlyHint/openWorldHint/idempotentHint/destructiveHint=false, so safety is covered. The description still adds non-obvious behavior: the redirected:true + requested_url signal and the 1-credit cost. It does not cover failure modes or throttling, but the added context is genuinely 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 purpose, then scope, then the sibling exclusion, then cost and a call example. Every sentence carries a distinct piece of information with no filler; the example is short and directly usable.

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

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

No output schema exists, and the description compensates by naming the returned fields and the redirect signal. Combined with the schema's own documentation of truncation (max_inline_chars/result_handle) and robots behavior, 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 100%, so the baseline is 3, but the description adds real meaning for the required url parameter that the schema does not: 'url is the final URL' and how a redirect surfaces via redirected/requested_url. It says nothing extra about user_agent, json_ld_types, respect_robots, or max_inline_chars, which the schema already documents at length.

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 ('extract a page's SEO metadata') and enumerates exactly what comes back: title, meta description, Open Graph tags, canonical URL, schema.org data. It also names the boundary against the sibling scrape path, so an agent can separate it from extract_structured, extract_text, and scrape 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?

Gives an explicit scope ('SEO metadata only') plus an explicit when-not: 'Not alongside a scrape of the same URL: scrape formats:["markdown","metadata"] returns both in one fetch.' This tells the agent both when to use this tool and when to prefer the alternative in a single fetch.

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, open-world, non-destructive semantics, so the bar is lower. The description still adds genuinely non-structured context: LLM-by-default with CSS selector fallback and a 3-credit cost. It leaves the verify_numbers/respect_robots behaviors to the schema, which is acceptable.

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 routing, then cost, then a concrete example. The packed single paragraph is dense but every clause earns its place; only the example pushes it toward the long side.

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, and cost, fallback behavior and the key alternative are covered. Minor gaps remain on prompt vs selectorHints interaction, but nothing that would cause a mis-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 coverage is 100% and the schema descriptions are rich (respect_robots, verify_numbers, user_agent all explain themselves), so the schema does the heavy lifting. The inline example illustrates url+schema usage but adds no syntax beyond what the schema already documents. Baseline 3.

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 (extract a specific data shape from a page via JSON schema) and adds the precise condition that makes it distinct: you can describe fields but not their selectors. The sibling contrast with scrape_structured makes the boundary unmistakable.

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

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

Gives both sides explicitly: use when you know the fields but not the selectors; do not use for stable markup where selectors are known, naming scrape_structured as the cheaper no-LLM alternative. Cost is stated too, which supports routing decisions.

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 cover the safety profile (readOnly/idempotent/non-destructive), and the description layers on cost (1 credit), the escalate billing model (projected 6, charged 1 when the plain fetch worked), the empty-shell succeeds-with-rendered:false behavior, and the robots.txt override being recorded against the API key — all behavior an agent cannot infer 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 purpose and cost signal, and every clause carries routing or billing information. It is dense — a single long paragraph — but wastes little; a bulleted split of use/avoid/cost would read faster.

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

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

For an 11-parameter tool with no output schema, the description covers routing, cost, escalation fallback, failure modes (binary refused, empty shell), and response flags (rendered:false, warning). An agent has everything needed to call it correctly and interpret the result.

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

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

Schema description coverage is 100% and the schema itself already documents defaults, enums, costs, and truncation semantics in detail. The description only reinforces output_format for RAG and selector/max_length behavior, adding marginal value over the schema. Baseline 3 is correct when the schema does the heavy lifting.

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+scope: 'a page's plain text or markdown with tags, scripts and styles removed - the cheapest read of a static HTML page.' It explicitly distinguishes itself from extract_content, scrape, and process_document by name, 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 explicit when-to-use (RAG → markdown, selector for matched elements, max_length to cap) and when-not-to-use with named alternatives for every exclusion (article pages, JS-rendered pages, link/metadata needs, binaries). The escalate guidance explains the exact condition that triggers the expensive path.

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, openWorldHint, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: default local Ollama endpoint with no API key, self-selection of an installed model, the need for a matching cloud API key on provider switch, and a credit cost (3 credits plus provider charge). It does not describe return shape or rate limits, but cost and provider prerequisites are the salient behavioral facts.

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 sentences, front-loaded with purpose, then provider mechanics, then exclusions, then cost. No filler and no repetition of schema fields beyond the minimal cross-reference needed for routing.

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 10-parameter, nested-object tool with no output schema, the description covers purpose, defaults, provider/auth prerequisites, sibling routing, and cost. The main remaining gap is the response shape, but read-only annotations and the absence of an output schema make that a minor omission rather than a blocking one.

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

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

Schema description coverage is 100%, so the schema baseline is 3. The description goes slightly beyond it by linking the `model` and `provider` parameters into one decision (local Ollama by default, or 'provider: "openai" or "anthropic" with the matching API key'), which the schema documents per-field but does not connect.

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 ('Extract data from a URL or text') plus the mechanism (natural-language prompt), and explicitly distinguishes itself from the nearest siblings by naming scrape_structured and extract_structured as the wrong choices. An agent can route correctly without opening any schema.

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

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

Gives explicit when-not conditions ('Not for known selectors (scrape_structured) or a schema-shaped result (extract_structured)') and a narrow conditional for list_ollama_models ('only when a model name is rejected'). Alternatives and their selection criteria 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context beyond that: it discloses the cost (1 credit), the timeout and custom headers support, the unprocessed return of the body, and the specific behavior of respect_robots (recording false setting against API key and returning a warning). It also explains max_inline_chars behavior (preview + result_handle). No contradictions.

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 three sentences, front-loaded with the core purpose and immediately contrasting with siblings. Every sentence earns its place: purpose, exclusions, features, cost, and an example. No fluff, no repetition of schema details.

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 6 parameters and no output schema, the description covers all necessary decision points: what to use it for, what to avoid, what it returns, cost, and edge cases (large results). It also names the sibling tools an agent might consider. The absence of an output schema is mitigated because the description explicitly states it returns the body and also mentions status, headers, and response time. The example shows a minimal valid call. Everything an agent needs to invoke correctly is 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 description coverage is 100%, so the baseline is 3. The description adds value by hinting at typical header usage ('e.g. auth tokens') and by including an example that demonstrates timeout usage. It also clarifies the implication of respect_robots and max_inline_chars in context, going slightly beyond the schema descriptions. However, the schema already fully documents each parameter, so the increment is modest.

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 clear verb-resource pair ('fetch a URL') and immediately distinguishes itself from siblings by specifying exactly what it returns (raw body, status, headers, response time) and what it does not (HTML rendering). It names the sibling 'scrape' and the extract_* family as alternatives, making differentiation explicit.

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

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

The description gives explicit when-to-use guidance (raw HTTP body, API responses) and when-not-to-use (HTML for reading, JS-rendered or bot-protected pages), and points to alternatives: 'scrape returns markdown from one fetch' and 'scrape, then stealth_mode'. It also includes a concrete example call, reinforcing correct invocation.

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, openWorld, non-destructive). The description adds non-annotation context: the 5-credit cost and a usage example. It stops short of describing output shape or how the 100-500 page analysis behaves, so 4 rather than 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 the core purpose, then the exclusion, cost, and example in tight order. Dense but no wasted sentences; the parenthetical gloss on llms.txt is slightly verbose.

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 tool with six parameters including two nested option objects and no output schema, the description gives purpose, routing, cost, and an example. It does not explain the returned file/handle behavior, but the safety annotations and full schema coverage make it adequate.

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 url, format, and the nested options. The description only adds an example call, not new semantics for the many nested analysis/output parameters. 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 (generate) and resource (llms.txt file for a website) and explains what llms.txt is. It is clearly distinguishable from fetch_url and other scraping siblings because it is about producing a file, not reading 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?

Explicitly scopes usage to site owners preparing for AI discoverability and names the exclusion: 'Not for reading a site's existing llms.txt (fetch_url on /llms.txt).' It also supplies cost (5 credits) and a concrete invocation example, leaving nothing 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, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: the batch must be already-paid, polling is only for async jobs, and there is a per-call credit cost. It does not describe the return envelope, but the schema's max_inline_chars description partially covers the preview/handle behavior.

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

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

The description is compact and front-loaded: it states the core purpose, key constraints, cost, and a concrete example in just three sentences. There is no filler or repetition of schema content.

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

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

For a simple paginated read tool with full schema coverage and supportive annotations, the description covers the essential operational details: how to identify the batch, when to poll, cost, and a working example. The large-result fallback is documented in the schema, so nothing critical is missing 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 coverage is 100%, so the baseline is 3. The description adds value with a concrete invocation example showing batchId, page, and pageSize in context, reinforcing the relationship between the batchId and the batch_scrape call. It does not add detail for max_inline_chars, but the schema already documents it fully.

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 a specific verb ('Retrieve'), a specific resource ('paginated results for a batch_scrape job'), and the key identifier ('batchId'). It also explicitly distinguishes itself from a scraping tool, which sets it apart from siblings like batch_scrape and 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 explicit when-to-use guidance: poll only async jobs, and don't use for sync batches whose results were already returned. It also clarifies it re-reads an already-paid batch and notes the cost, leaving no ambiguity about when this tool applies.

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 bar for additional behavior is lower. The description adds meaningful context: the Ollama prerequisite (localhost:11434 or $OLLAMA_BASE_URL), the associated credit cost, and the 'installed locally' scope. It doesn't cover error behavior, but that is a minor gap for a simple read-only list.

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

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

Three sentences, each earning its place: the core operation, the usage guidance, and the prerequisite/cost. The key information is front-loaded and there is no wasted 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 zero-parameter, read-only list tool, the description covers purpose, when to use, the alternative, the infrastructure prerequisite, and cost. The output is implied by the purpose ('list... to choose a model'), so nothing needed for correct invocation 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?

There are zero parameters, so the baseline is 4. The description correctly avoids inventing parameter guidance and instead clarifies the output's intended use ('model' value for extract_with_llm), which adds value beyond the empty 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 ('List'), a precise resource ('Ollama models installed locally'), and a clear purpose (choosing a model for extract_with_llm). It is distinct from all sibling tools and leaves no ambiguity about what the tool returns.

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 explicitly says the tool is not needed before every extraction, names the alternative behavior (extract_with_llm picks a default), and gives two concrete conditions for calling it: a rejected model name or a need for a specific size. This is excellent 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?

Discloses the single most surprising trait — the tool applies nothing: no later fetch_url/scrape/stealth_mode call picks up the values, nothing routes through a proxy, the IP is unchanged and geo-blocks are not lifted. It also states the cost (2 credits). These are exactly the side-effect expectations an agent would otherwise wrongly assume from a 'configure' operation.

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

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

Front-loaded with the purpose and the critical no-side-effect constraint, then the value-routing recipe, the exclusion, and cost. Dense but every clause earns its place for a 15-parameter, 8-operation tool; nothing is redundant.

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

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

Given 15 parameters, nested objects, 8 enum operations, no output schema and an open-world hint, the description covers return semantics, side-effect profile, cost, and how values flow to named siblings. An agent has everything needed to select and 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 coverage is 100%, so the schema carries the per-parameter detail and the baseline is 3. The description goes beyond it with the credential-relevant advice to 'pass countryCode on every call' (since omitted calls silently reuse the last configure_country state), plus a worked example and the per-operation return descriptions.

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 — 'look up the locale settings of a country' and 'run a search targeted at a country' — and immediately differentiates from siblings by naming the two operations and their outputs (language, Accept-Language, timezone, currency, etc.). The closing example call pins the shape down concretely.

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 about when to use it (setting up locale for a request), when not to ('Not for an ordinary page read (scrape)'), and which alternatives to route results to (fetch_url headers, stealth_mode stealthConfig, search_web localization). It even notes scrape has no locale parameter, ruling out a misuse path.

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, idempotency, non-destructiveness, and open-world access. The description adds meaningful behavior beyond that: it reads sitemap.xml when available and otherwise follows links, does not fetch page bodies, and costs 2 credits. This is operational context the agent can use when choosing among scraping tools.

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

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

The description is compact and front-loaded: purpose first, then exclusions, then cost, then an example. Every sentence adds useful information, and no space is wasted restating the name 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 complex 11-parameter tool with an output schema and full annotation coverage, the description supplies the routing context an agent needs: what it does, what it does not do, how it discovers URLs, and its cost. Return-value details are 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?

Schema description coverage is 100%, so all 11 parameters are already documented in the schema. The description mentions include_sitemap and max_urls only in an example and does not add syntax, defaults, or constraints beyond what the schema provides. This meets the baseline of 3 when the schema carries parameter semantics.

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: list a site's URLs without fetching page bodies. It also distinguishes the tool from siblings by naming scrape, crawl_deep, and extract_links as wrong alternatives. An agent can identify the correct tool without opening any schema.

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

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

It gives explicit when-to-use guidance ('list a site's URLs without fetching page bodies') and when-not-to-use guidance ('Not for page content', 'not for the links on one page'), naming the alternatives for each excluded case. The sitemap-first fallback behavior also tells the agent how the tool will go about discovery.

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 safety profile (readOnly, idempotent, non-destructive, openWorld); the description adds substantive behavioral context beyond them: 2-credit cost, parser routing, refusal behavior, page-read reporting with maxPages defaulting to 100, and return shape (sections, metadata, word count). This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with purpose and cost, followed by routing rules, return shape, and an example. Dense but every sentence carries signal; the 'body decides how it is read' phrasing is slightly convoluted but still earns its place by clarifying parser routing.

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 compensates by describing returns (structured sections, metadata, word count, pagesRead). Combined with full parameter coverage and annotation safety hints, an agent has everything needed to call this 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 genuine meaning the schema does not: sourceType 'url' still routes a PDF to its parser, maxPages defaults to 100, and a concrete call example with source/sourceType. It does not explain options/redact_pii/user_agent beyond the schema, hence 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 (extract text from a PDF or DOCX) and enumerates the document types (research papers, contracts, reports). It explicitly distinguishes itself from the sibling 'scrape' by declaring what it is not for, so an agent can route correctly 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 explicit when-to-use (PDF/DOCX URLs or files), what is refused (images, archives, refused by name), an edge case (an HTML URL is accepted but ordinary web pages belong to 'scrape'), and names the alternative tool. 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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: the 1-hour retention window, the preview behavior, the credit cost, and the semantics of each operation (search, slice, lines, json_path). This goes beyond the annotations without contradicting them.

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 a single dense paragraph that front-loads the primary use case and ends with an example. It is somewhat lengthy but every sentence earns its place by covering scope, operations, exclusions, cost, and an example. A more structured layout could improve skimmability, but it remains efficient.

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 an output schema exists (not shown but present), the description need not detail return formats. It covers the main trigger, all operations, exclusions, cost, and handle validity. It does not explicitly mention error cases (e.g., expired handle), but the output schema likely handles those. Overall, it's sufficiently 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 coverage is 100%, so every parameter is documented. The description adds operation-specific meaning (e.g., 'search finds a literal query with offsets and context', 'json_path reads one subtree') and a usage example that clarifies how parameters combine. This enriches understanding beyond the schema's basic field descriptions.

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 the tool reads truncated results, identifies the trigger condition (truncated: true with a result_handle), and explicitly distinguishes itself from fetching tools by instructing not to call the original tool again. It also names sibling tools indirectly and lists distinct operations, making its scope 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 provides explicit when-to-use (truncated results) and when-not-to-use (whole results, not a fetching tool) guidance. It also gives a concrete example call and notes the 1-hour handle validity, which helps the agent decide when to invoke this tool versus alternatives like fetch_url or crawl_deep.

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 safety profile (readOnly, idempotent, openWorld, non-destructive), but the description adds substantial behavioral context beyond them: cost (5 credits), credential requirements (free, no Reddit credentials vs reddit_api needing env vars), backend ordering and fallback, timeout/retry behavior with narrower windows and window_applied reporting, and PullPush's refusal of automated clients. This is far richer than 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 purpose, then modes, then scoping behavior, then fallback/retry details, ending with cost and a concrete example. It is dense and every paragraph carries information, but a few clauses overlap with schema enum text (mode/source definitions) and could be trimmed.

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 read-only tool with 10 optional params, an output schema, and no required fields, the description supplies everything an agent needs: when to use each mode, credential prerequisites, backend selection and fallback behavior, credit cost, and the result-metadata signals (fallback_used, window_applied). Return-value explanation is rightly 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?

Schema coverage is 100%, so parameters are already documented, but the description adds routing semantics the schema cannot express — how mode:'thread' requires link_id, that unscoped keyword searches use web discovery plus archive reads, that unscoped comment searches search each post's comments, and that fallback_used/window_applied appear in results. It adds real meaning beyond the enum descriptions, though it restates mode/source enums already in the schema.

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

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

Opens with a specific verb and resource ('search Reddit posts or comments, or read a full comment thread') and immediately distinguishes itself from the scraping siblings by explaining why it exists (reddit.com blocks direct scraping, so it reads Arctic Shift). An agent can tell it apart from scrape/fetch_url without opening any schema.

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

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

Explicitly states when NOT to use it ('Not for reddit.com URLs via scrape or fetch_url (blocked) - use mode:'thread' with the post's link_id') and names the alternative to use instead. It also routes between modes (posts vs comments vs thread) and explains which mode fits scoped vs unscoped searches.

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, so the bar is lower, yet the description adds genuinely new behavior: per-format warnings never fail the whole call, escalate runs the plain fetch first and only retries on a wall, the projected-vs-actual charge behavior, and the 2-credit base cost. That is context an agent cannot derive from 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?

Front-loaded with the core purpose and default, then progressively adds format details, alternatives, escalation, and cost. It is a single dense paragraph of mostly load-bearing sentences, though the length and lack of breaks make it slightly harder to scan than it needs to be.

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

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

For a 12-parameter, nested-format tool with a rich schema, output schema, and annotations, the description covers the decision points an agent needs: default format, combining formats, cost, escalation semantics, redaction, robots behavior, and which sibling to pick. Nothing material is left to 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%, so the baseline is 3; the description still adds meaning beyond the schema by explaining highlights (+1 credit, no model, returns verbatim units with offsets), branding as static design tokens, and that one extra fetch is avoided by combining formats. It does not add much on escalate/timeout/redact beyond what the schema already states.

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 ("read one page") and enumerates exactly what it can return (markdown default plus html, rawHtml, text, links, metadata, branding, screenshot, structured json, highlights). It explicitly separates itself from fetch_url, extract_* tools, scrape_with_actions, and batch_scrape, so an agent can route without opening another 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 explicit when-to-use guidance ("Ask for every format you need in the same call instead of fetch_url followed by extract_* tools") and an explicit exclusion list: not for raw API/JSON bodies (fetch_url), click/login pages (scrape_with_actions), or 2+ URLs (batch_scrape). It even states a preference over the client's built-in web fetch.

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 annotations, it discloses the critical row-alignment gotcha (data.price[0] need not belong to the same row as data.name[0]), the cost of 2 credits, and the meaning of row_selector. This is exactly the kind of non-obvious behavior an agent needs 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?

The description leads with the decision rule, then covers exclusions, the key behavioral warning, cost, and an example with no filler. Every sentence contributes necessary operational information.

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

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

Despite having no output schema, the description explains the shape of returned data (parallel arrays vs row-aligned objects) and gives enough context for an agent to invoke correctly. Together with the rich input schema, this is complete for a read-only extraction 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?

The schema already covers all 6 parameters in detail, so the baseline is 3. The description adds value with a concrete usage example and clarifies how selectors and row_selector work together, but it does not substantially redefine the parameter meanings beyond the schema descriptions.

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 (scrape structured data with exact CSS selectors) and differentiates it from LLM-driven extraction. It is immediately clear this tool is for well-structured pages with known markup.

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 when-to-use condition (you know exact selectors, consistent markup) and states what it is not for (varying markup or unnamed selectors), pointing to extract_structured / LLM-driven extraction as the alternative. This lets an agent select correctly among many 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 already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description still adds real context: 1 credit cost, page templates returning one record vs list connectors returning N, the Arctic Shift archive behavior for reddit-thread, and the retired templates (linkedin-profile, tweet) rejected by robots.txt. Minor gap: inline-preview/result_handle behavior lives in the schema, not here.

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 usage trigger and mode enumeration; each sentence carries weight. The long parenthetical inventory of template names and job-board vendors is dense but earns its place as discoverability aid. Slightly overlong, but 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?

For a 7-param tool with a nested `params` object and no output schema, the description covers modes, cost, required-vs-optional param logic, example calls, and failure/exception cases. An agent has everything needed to select and 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by grouping the parameters into three modes and showing worked invocations for template+url, auto, and params-driven list connectors, which clarifies how `url` vs `params` are selected — information the schema documents only per-field.

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 (fetch structured data via pre-built site/API templates) and immediately contrasts itself with the sibling `scrape` for sites without templates. The three operating modes (template id, auto, list) make the tool's scope 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?

Explicit when-to-use (well-known site or platform API without writing selectors), when-not (no template → use `scrape`, and `template:"list"` to check), and it names concrete alternatives/enumeration paths. Includes the retired-template behavior so the agent knows a failed name returns a reason rather than an error.

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 annotations (which only cover safety/idempotency), it discloses robots.txt enforcement, per-navigation bot-wall reporting with `blocked`/`navigations`/`finalUrl` fields, ref invalidation on navigation, consent-banner semantics, stealth engine resolution, proxy-rotation constraints, and screenshot resource storage. It also states cost (5 credits) and the executeJavaScript env-var gate, which no structured field 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?

The when-to-use clause is front-loaded and nearly every sentence carries operational value (workflow, restrictions, cost, example). It is nonetheless a single dense paragraph with no visual structure, which makes it heavier to scan than it needs to be.

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

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

For a 13-parameter tool with nested objects, no output schema, and heavy side effects, the description covers the workflow, failure/blocking semantics, navigation result shape, screenshot retrieval, and a worked example. Details it omits (formAutoFill, redact_pii, max_inline_chars/read_result routing) are fully documented in the schema itself.

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 the 13 parameters and baseline is 3. The description adds procedural meaning the schema cannot: the snapshot-first workflow, stable @e1 refs in document order (including shadow roots and iframes), and that refs are invalidated by navigation so a re-snapshot is required.

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 ('interact with a page before scraping') and enumerates the interactive capabilities (login, click, fill forms, scroll, wait). It explicitly distinguishes itself from siblings by naming what it is NOT for: 'Not for pages that render without interaction (scrape) and not as the first attempt on a blocked site (stealth_mode operation:"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 opens with an explicit when-to-use clause ('Use this when you must interact with a page before scraping... for SPAs, login-gated content, or multi-step flows') and closes with explicit when-not-to-use plus the alternative tool for each exclusion. Alternative routing is unambiguous.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so safety is covered. The description adds genuinely non-structured operational context: cost is 5 credits per query, batching 10 queries costs the same as making them separately, and results are returned per query. It stops short of rate limits, failure modes, or provider-selection trade-offs, so it is not a full 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?

Purpose and the snippet-first rule are front-loaded, and nearly every sentence carries routing, cost, or workflow information. The exclusion list is a single run-on sentence with four parenthetical branches, which is dense, and the cost point is stated twice (batching line and standalone 'Cost: 5 credits per query').

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 21-parameter tool with nested objects and an output schema, the description covers the decisions an agent actually needs: which tool to pick, how to batch, what it costs, and when a snippet suffices. Return values need not be explained given the output schema. It is silent on provider choice (crawlforge vs searxng) and the ranking/dedup knobs, which a 100%-covered schema mitigates.

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 baseline is 3. The description reinforces the critical query/queries mutual exclusion with a concrete worked example (query, limit, time_range) and states the per-query cost of batching, which the schema only partly conveys. The remaining 19 advanced parameters get no description-level treatment.

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 pages for a query') and enumerates what comes back (titles, URLs, snippets, optional metadata) plus the filter dimensions. It goes further by naming the siblings it is not for (scrape, reddit_search, serp_rank, deep_research), so an agent can route correctly without opening any schema.

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

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

Explicit when-to-use ('preferred over the client's built-in web search'), when-not ('not for a URL you already have', Reddit, domain rank, multi-source reports), and names the alternative tool for each exclusion. It also gives a workflow rule: try snippets first, scrape only when the body is needed.

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, idempotent, non-destructive), and the description adds rich context beyond them: the sampling variability of Google results, the seResultsCount field to distinguish samples, credential dependency, the configured:false outcome, and exact credit cost. This is unusually complete behavioral 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?

The description is dense but front-loaded with the core purpose and exclusion, followed by sampling, credential, and cost notes, ending with a concrete example. Every sentence earns its place and no redundant phrasing is present.

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 an output schema exists, the description needn't explain return values, and it covers the remaining gaps an agent needs: credential prerequisites, cost, sampling caveats, sibling exclusion, and a usage example. Nothing material is missing 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 100%, so the schema already documents all seven parameters in detail. The description provides a concrete usage example but adds no parameter-specific meaning beyond what the schema already states (e.g., host matching, depth billing, location codes). 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 and resource: check where a domain ranks in Google's organic results for a keyword, and explicitly distinguishes this from Custom Search order. It also names the sibling it is not (search_web), 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?

Explicitly says when not to use it ('Not for general search (search_web)'), gives operational guidance about comparing multiple samples before reading a rank change, and states credential requirements plus the exact behavior when unconfigured (returns configured:false, do not retry). Alternatives and exclusions are unambiguous.

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

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

Goes well beyond the annotations: discloses cost (5 credits per browser op; 1 for configure/get_stats/cleanup), that robots.txt is respected on every navigation, that configure stores nothing so stealthConfig must be re-passed, and which engine ran. Annotations only cover the safety/idempotency profile, so this context is genuinely additive.

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 trigger condition and the anti-detection value before the operational details, and every sentence carries information. It is dense and long, but not padded; the cost and example are the only borderline lines.

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 12-param, nested-object tool with no output schema, it covers trigger, alternatives, cost, engine selection, config persistence, and robots behavior. It partially signals return content (engine name, redaction counts) but does not fully characterize output shape, which is acceptable given the depth provided.

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 the operation lifecycle framing (scrape tears down; create_context/create_page/cleanup for multi-step; configure validates and stores nothing), which clarifies how parameters interact across calls beyond the enum's own text.

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: renders in a real browser with randomized fingerprints when a site blocks normal scraping, naming the anti-detect stack (Camoufox/Chromium). It explicitly distinguishes itself from the sibling 'scrape' tool, so an agent can route 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 explicit when-to-use (site blocks: Cloudflare, Datadome, bot-detection), when-not ('Not a first choice: try scrape first'), and the trigger to switch (403/429/CAPTCHA/challenge page or empty shell). It also maps operations to workflows: scrape as the one-shot path vs create_context/create_page/cleanup for multi-step work.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds meaningful behavioral context: it accepts text not URLs, performs extractive or abstractive summarization, leverages Ollama/sampling for abstractive rewrites, and costs 4 credits. This goes beyond what annotations provide, though it doesn't disclose return format or edge-case behavior.

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

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

The description is dense but organized: it starts with the core purpose, then input constraint, a usage heuristic, cost, and a concrete example. No sentence is wasted; the structure front-loads the main action and defers cost and example details.

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

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

For a two-parameter tool with high schema coverage but an empty options schema, the description covers how to invoke it (text plus optional options), what input type to pass, and an example. It lacks an explicit statement of return value shape, which matters because there is no output schema; however, the core invocation requirements are adequately specified.

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% for both properties, but the 'options' property is an empty object in the schema, providing no usable semantics. The description compensates with an example showing summaryLength and summaryType, and clarifies that 'text' should be markdown from a scrape result. This adds real meaning beyond the schema, especially where the schema is empty.

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 ('condense') and names the resource ('text you already hold'), and distinguishes itself from URL-input tools by stating 'Takes text, not a URL.' It also lists output forms (briefing, comparison, shorter LLM context) and methods (extractive/abstractive), which clarifies exactly what it does.

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 provides explicit when-to-use context: summarizing text already held, and an explicit when-not-to-use: 'Not needed for text short enough to summarise in context yourself.' It also directs users to pass markdown from a scrape result, implying the preceding step. It doesn't name a specific sibling tool as an alternative, but it gives enough 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description doesn't need to re-state safety. It does add valuable behavioral context beyond annotations: webhook/scheduled monitoring support, hosted execution on CrawlForge's servers with email and signed webhooks, a cost of 3 credits, and that repeated compares are expected. It does not discuss rate limits, auth prerequisites, or result-size behavior in depth, so it falls just short of a 5.

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

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

The description is front-loaded with the primary purpose, then workflow, then differentiation, then cost, then example. No sentence is wasted; it covers a complex tool efficiently in a compact block 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?

Given 16 parameters, deep nested objects, and no output schema, the description does a good job covering the operational workflow and the hosted-versus-local distinction. It doesn't explain return shapes (acceptable since no output schema exists, though some hint of result format would help) and omits coverage of less-common operations like get_history, export_history, or create_alert_rule that appear in the schema union. Adequate for most calls but not exhaustive.

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 16 parameters in detail (including nested objects like monitoringOptions, scheduledMonitorOptions, trackingOptions). The description adds a small amount of meaning by naming two specific operations (create_baseline, compare) and the hosted option semantics, but largely repeats what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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: monitor a URL for content changes over time, with concrete use cases (competitor pricing, regulation updates, product availability). It explicitly distinguishes itself from the sibling 'scrape' by stating 'Not for a one-off read (scrape)', which is the key differentiator an agent needs.

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 provides explicit workflow guidance: start with operation:"create_baseline", then periodically use operation:"compare", and notes that repeated compare calls are expected. It also names the alternative for one-off reads ('scrape') and gives exclusion guidance, which is exactly the when-to-use/when-not-to-use clarity that helps an agent select correctly.

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