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 readOnly, openWorld, non-idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new information by disclosing the credit price and that cost grows with page count, but says nothing about crawl duration, rate limiting, or that huge results spill into a result_handle (that detail lives only in the schema).

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

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

Three tightly packed sentences: purpose, exclusions with alternatives, cost, then an example. Front-loaded and no filler; every clause carries routing or pricing information.

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

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

For a 17-parameter, nested-schema tool with an output schema and full annotations, the description covers the decision-relevant essentials: scope, alternatives, cost, and a usage example. Minor gap: it never hints at the login/session workflow or the preview-plus-handle return path, though both are documented in the 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 a 3 is the baseline; the description earns a bump by showing a realistic invocation that anchors typical values for max_depth, max_pages, and extract_content on a docs site. It does not touch the session, redaction, or inline-limit parameters, which is acceptable given the schema already documents them 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?

States a specific verb and resource (fetch many pages of one site by following links) plus concrete scenarios (knowledge base, docs index, full-site audit). It also explicitly sets itself apart from scrape, batch_scrape, and map_site, 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?

Gives explicit when-to-use framing and three named alternatives with the condition that selects each ('Not for a single page (scrape), a known URL list (batch_scrape), or URL discovery alone (map_site, cheaper)'). The cost comparison to map_site further aids the decision.

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 declare read-only, idempotent, open-world behavior, but the description goes further: exact values with no LLM in the extraction path, large-payload handling via previews and result handles, cache reuse for 10 minutes, and escalation behavior with projected versus actual cost. These are meaningful operational traits 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?

The description is front-loaded with the core use case and alternatives, and every part is relevant to calling the tool correctly. It is dense and somewhat long, with some repetition of schema-level details, but the length is justified by the tool's complexity.

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 extraction tool with no output schema, the description covers framework scope, extraction guarantees, large-result handling, caching, escalation behavior, and cost. An agent has enough context to invoke it correctly without opening sibling tools.

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

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

Schema coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description still adds useful cross-parameter workflow guidance: use keys_only for discovery, find to locate matching paths, path to scope large payloads, and read_result for oversized results.

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 action and resource: extracting a page's embedded JavaScript framework state. It explicitly distinguishes this from rendered-text scraping and from sites without a framework payload, so an agent can select it confidently.

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 a clear triggering condition (data lives in embedded JS state), lists concrete frameworks and payload names, and explicitly excludes the sibling use cases: rendered text should use scrape, and framework-less sites are out of scope. It also explains when to use path, keys_only, find, and escalate.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: PDFs and binaries are refused with a pointer to process_document, empty client-rendered shells succeed with rendered:false plus a warning, and the escalated retry only fires when the plain fetch is walled. It also discloses the economics (1 credit, projected 6 on escalation, charged 1 when the plain path works) and the 10-minute session cache.

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

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

Purpose is front-loaded, then exclusions, then edge-case behavior, then cost, then a concrete example — a sensible ordering. It is a single very dense paragraph with stacked clauses (escalation pricing, cache, robots) that takes effort to parse, but almost every sentence carries information an agent needs.

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

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

There is no output schema, and the description compensates by explaining what the caller will see: rendered:false with a warning on empty shells, type "other" for non-http schemes, and a result_handle path for oversized results. For a 9-parameter fetch tool with a non-trivial cost model, nothing essential 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, and the schema descriptions for escalate, maxAge and max_inline_chars are already very detailed. The description still adds value the schema does not: filter_external's effect in output terms and the fact that mailto:, tel: and javascript: links come back as type "other".

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?

Starts with a specific verb and resource ('list the hyperlinks on one page') and immediately supplies three concrete use cases (crawl seed list, broken-link audit, related resources). It explicitly distinguishes itself from map_site for whole-site scope and from scrape with links format, so an agent can pick 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-not guidance: not for a whole site (use map_site) and not alongside a scrape of the same URL (scrape's links format returns both in one fetch). It also states when to set escalate:true and when to pass maxAge:0, which is real routing guidance rather than implied context.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description layers on non-obvious behavior the annotations cannot express: redirect provenance (redirected:true plus requested_url), a 10-minute session cache, and a stated cost of 1 credit per call. That is exactly the additional context this dimension rewards.

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

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

Front-loads the purpose and the exclusion before caching and cost details, and ends with a runnable example. It is dense — the middle sentence packs redirect semantics, the scrape alternative, caching, credit cost and maxAge into one long clause — but nearly every clause carries information an agent needs.

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

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

For a 6-parameter read tool with no output schema, the description names the returned fields, explains redirect output, discloses caching and cost, and names the cheaper alternative. The remaining parameters are exhaustively documented in the schema, so an agent has everything needed to call this correctly and to decide against it.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by clarifying that the returned `url` is the final post-redirect URL and by surfacing the credit cost that no schema field states. It does not touch user_agent, respect_robots, json_ld_types or max_inline_chars, but those are fully documented in the schema, so the gap is small.

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 scope statement — 'a page's SEO metadata only' — followed by an explicit enumeration of what comes back (title, meta description, OG tags, canonical URL, schema.org data). That verb+resource+scope combination makes it immediately distinguishable from generic scrape and from extract_structured/extract_links 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?

Explicitly routes the agent elsewhere — 'Not alongside a scrape of the same URL: scrape formats:["markdown","metadata"] returns both in one fetch' — naming the sibling and the exact parameter combination. It also states the repeat-request rule (same page with different formats/paths/selectors reuses the session copy for 10 minutes at 1 credit) and the escape hatch maxAge: 0.

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?

Although annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior, the description adds material context: LLM default with CSS fallback, session reuse for 10 minutes at 1 credit, maxAge override, and a 3-credit cost. This is substantially more than the annotations provide.

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: use case, mechanism, exclusion, caching/cost, and example. Every sentence adds decision-relevant information, and the example is compact enough to be useful without dominating.

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 a full input schema, output schema, and rich annotations, the description supplies the remaining decision-critical context: when to choose this over sibling tools, LLM fallback behavior, caching semantics, and cost. Nothing essential 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?

Schema coverage is 100%, so the schema carries most parameter meaning. The description still adds useful semantics for maxAge caching behavior and a concrete schema example; advanced parameters such as verify_numbers and respect_robots are left to the well-documented schema.

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

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

States a specific verb (extract structured data), resource (page), and mechanism (JSON schema when selectors are unknown). It explicitly distinguishes from scrape_structured, making sibling selection straightforward.

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 context ('describe the fields but not their selectors') and when-not-to-use guidance ('stable markup whose selectors you know'), naming the cheaper alternative scrape_structured.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description nonetheless adds substantial non-obvious behavior: 10-minute session cache reuse at 1 credit, escalate projected at 6 but charged 1 on a successful plain fetch, binary refusal, and an empty shell returning rendered:false with a warning. Remaining gaps (output shape for the redaction field, pagination/truncation interaction) are minor, but the bulk of behavior is disclosed rather than omitted.

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 primary exclusion are front-loaded, which is good, but the prose is a dense run-on of parentheticals that restates schema text (max_length, maxAge, output_format defaults) and repeats the escalate cost model. For a 12-parameter tool the length is defensible, yet trimming the schema-echoing clauses would improve scanability.

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, no-output-schema tool, everything an agent needs before calling is present: cost, caching window, escalation semantics and its failure conditions, refusal cases, and the sentinel fields returned (truncated:true, rendered:false, redaction:{entities,count}). No critical decision-relevant gap remains.

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 per-parameter baseline is satisfied by the schema itself. The description still adds cross-parameter meaning the schema does not carry: output_format:"markdown" as the RAG convention, escalate's two-stage cost/retry model interacting with escalate_engine, and maxAge:0 as the cache-bypass switch. It stops short of explaining redact_pii or user_agent, 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+resource ("plain text or markdown with tags, scripts and styles removed") and immediately positions it as "the cheapest read of a static HTML page." It explicitly separates itself from extract_content, 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?

Gives explicit when-to-use (RAG → markdown, selector for scoped reads), explicit when-NOT-to-use with a named alternative for each case (article pages → extract_content, JS pages → scrape, links/metadata → scrape, PDFs → process_document), plus guidance on escalate and maxAge:0. Exclusions and alternatives are both present.

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

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

Annotations already establish read-only, open-world, non-destructive behavior, and the description adds useful context beyond them: local Ollama defaults require no API key, cloud providers need matching keys, callers pay 3 credits plus provider charges, and cached page reuse costs 1 credit for 10 minutes unless maxAge is 0. These details materially improve invocation planning without contradicting 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?

The description is front-loaded with the core purpose, then layers in provider defaults, exclusions, model fallback, caching, and cost. Despite its length, each sentence carries operational information for a complex 11-parameter tool.

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

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

Given the tool's complexity, rich schema, and annotations, the description covers the critical invocation context: alternatives, provider setup, model defaults, caching, and cost. It does not describe the returned extraction shape or provenance/error behavior, which leaves a modest gap because there is no 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 the schema already documents all 11 parameters in detail. The description still adds useful semantic context for model/provider selection and the cost/caching implications of maxAge, though it leaves several behavioral controls such as verify_numbers and respect_robots to the schema.

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

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

The description states a specific verb and resource: extract data from a URL or text using a natural-language prompt. It explicitly distinguishes this tool from scrape_structured and extract_structured, so an agent can identify its role among 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 names when not to use this tool and which alternatives to use instead: scrape_structured for known selectors and extract_structured for schema-shaped results. It also gives a clear conditional path for list_ollama_models and explains provider/model selection.

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 (readOnly, idempotent, openWorld), the description discloses the 10-minute session cache and 1-credit cost, how maxAge: 0 forces a fresh fetch, that redirects and final_url are reported, and that headers/timeout are supported. These are non-obvious operational traits an agent needs before calling.

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

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

Purpose is front-loaded and every sentence carries routing, cost, or caching information with no filler. It is dense and slightly long, but the density is justified by the number of distinct behaviors covered.

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

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

No output schema exists, yet the description explicitly lists return contents (body, status code, headers, response time, redirected, final_url), plus cost, caching, and the double-fetch pitfall. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description still adds value by explaining the credit/caching semantics of maxAge and giving a concrete usage pattern for headers (auth tokens) plus an example call. It doesn't expand on user_agent or respect_robots, which remain schema-only.

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 ('raw HTTP body - JSON, XML, plain text, an API response') and explicitly states what it returns ('Returns the body unprocessed'). It names the exact sibling it is not (scrape, extract_*, stealth_mode), so an agent can route 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 explicit when-to-use (raw bodies, status codes, headers, timing) and explicit when-not-to-use with the named alternative for each case: HTML to read → scrape; JS-rendered/bot-protected → scrape then stealth_mode. Alternatives and conditions are fully spelled out.

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 a cost disclosure (5 credits), which is real value not present in structured fields. It stops short of saying what is returned (generated text vs. files written to the site) or that generation involves crawling and may be slow, which analysisOptions.maxPages strongly implies.

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?

A single dense sentence chaining purpose, exclusion, cost, and example with zero filler. The most decision-relevant facts (what it produces, when not to use it) come first.

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 6 parameters, nested objects, no output schema, and full schema coverage plus annotations, the description covers purpose, routing, and cost adequately. The gap is the return shape and the fact that a deep analysis (up to 500 pages) may be long-running and produce a result_handle instead of inline content.

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%, including enum and nested-object descriptions, so the baseline is 3. The description adds only an example call with the required url and does not explain format, complianceLevel, or analysisOptions trade-offs 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?

States a specific verb (generate) and resource (llms.txt file) and even defines the artifact for an unfamiliar agent. It explicitly distinguishes itself from fetch_url reading an existing /llms.txt, so it is separable from siblings without inspecting schemas.

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

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

Names the audience and intent (site owners preparing for AI discoverability), gives an explicit when-not ('Not for reading a site's existing llms.txt (fetch_url on /llms.txt)') with the named alternative, and includes a concrete invocation example.

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 declare read-only, open-world, idempotent, non-destructive behavior, so the bar is lower. The description adds useful operational context: no page-body fetching, sitemap.xml preference with link-following fallback, and a concrete cost of 2 credits. It does not discuss rate limits or large-result handling, but those are covered in schema details.

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 primary purpose and exclusions, then adds cost and a compact example. Every sentence carries useful selection or invocation information with no 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?

Given the rich schema, output schema, and annotations, the description supplies the critical context an agent needs: purpose, alternatives, non-body-fetching behavior, sitemap fallback, and cost. Parameter and return-value details are appropriately left to the structured 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 input schema. The example illustrates a valid parameter combination (url, include_sitemap, max_urls), but the description does not add syntax or meaning beyond what the schema already provides.

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

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

States a specific verb and resource ('list a site's URLs'), clarifies the mechanism ('without fetching page bodies', sitemap fallback), and explicitly distinguishes itself from sibling tools scrape, crawl_deep, and extract_links.

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 and when-not-to-use guidance: use for URL discovery without page bodies; do not use for page content (scrape, crawl_deep) or single-page links (extract_links). The named alternatives leave no inference required.

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 safety is covered; the description adds real value with cost (2 credits), the refusal behavior for unreadable bodies, and the pagesRead/maxPages=100 detail. However it never mentions the truncation path — that a large result comes back as a preview plus result_handle for read_result — which is the most consequential behavior for downstream flow, so it falls 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 purpose is front-loaded in the first clause, but the rest is one dense paragraph of semicolon-chained caveats and parentheticals that is harder to scan than it needs to be. Nearly every clause carries information, so little is wasted, yet the lack of breakdown costs readability.

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-parameter tool with nested objects and no output schema, the description does well: it states the return shape (structured sections, metadata, word count, pagesRead) and the main refusal and directory constraints. The gap is the large-result/handle handoff and the redaction result field, both of which affect what the agent must do next.

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 all seven parameters including the redact_pii sub-object and max_inline_chars. The description adds genuine meaning for sourceType ('a PDF or Word document served under sourceType "url" still reaches its parser') and maxPages defaulting to 100, which is above baseline, but it says nothing about redact_pii, user_agent, or respect_robots and omits the options object entirely.

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 ('extract text from a PDF or DOCX') and scopes it to concrete document classes (research papers, contracts, reports). It explicitly distinguishes itself from the nearest sibling by saying it is 'Not for ordinary web pages (scrape)', 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 an explicit when-not and the alternative ('Not for ordinary web pages (scrape), though an HTML URL is accepted'), plus the accepted file extensions and the dot-directory/CRAWLFORGE_ALLOWED_DIRS constraint. The inline example anchors the call shape for the common URL case.

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 readOnly/idempotent/non-destructive, and the description adds the facts annotations cannot: a 1-hour retention window, preview-plus-handle behavior, and a cost of 1 credit. That is exactly the extra context an agent needs before deciding to spend a call.

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 trigger condition (truncated: true + result_handle) followed by usage constraints, operations, cost, and an example. Dense but nearly every clause carries information; the operation list partially restates the enum descriptions in the 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 an 8-param tool with an output schema and full annotations, the description covers the trigger, the alternatives, retention, cost, and per-operation routing. Nothing an agent needs to invoke 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; the description earns above that by explaining what each operation does in practice and supplying a concrete call example. It does not touch max_inline_chars or the offset/length defaults, but those are fully documented 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?

States a specific verb+resource (read a result that returned truncated: true with a result_handle) and immediately scopes it against the obvious mistake — it is explicitly 'Not a fetching tool'. No sibling does this job, and the description makes that separation obvious.

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-to-use rules: never re-call the original tool while the handle is valid, and do not use it for a result that arrived whole. It also routes among the four operations by naming the situation each fits (search, slice, lines, json_path for crawl_deep pages, batch results, fetch_url JSON bodies).

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 read-only/idempotent annotations: it discloses the cost (5 credits), backend order and fallback (Arctic Shift then PullPush), the PullPush refusal, timeouts with narrowed retry windows, and the window_applied/fallback_used reporting fields. The one gap is pagination/cursor behavior for large result sets, but overall this is unusually transparent for a search tool.

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

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

Purpose and the key exclusion are front-loaded, and the mode/fallback details follow in a logical order. It is dense and long for a search tool, with some near-duplication between the fallback sentence and the source enum text, but nearly every clause carries 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?

For a 10-parameter, multi-mode tool with three backends, the description covers everything an agent needs to call it correctly: mode selection, credential-free access, cost, routing/fallback outcomes, and the correct alternative path for URLs. Return shape is covered by the output schema, so no further detail is required.

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 earns above that by explaining mode-dependent semantics the schema only hints at — how scoped vs. unscoped keyword searches execute differently, and what 'thread' returns (post plus nested comment tree). It does not restate every parameter, but the mode behavior it adds is genuinely load-bearing.

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

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

The opening sentence states the specific verb and resources (search Reddit posts/comments, read a full comment thread) and explains the mechanism (Arctic Shift archive rather than scraping). An agent can distinguish it from scrape/fetch_url without inspecting the schema.

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

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

Explicitly names the wrong path ('Not for reddit.com URLs via scrape or fetch_url (blocked)') and gives the correct alternative ('use mode:'thread' with the post's link_id'). It also explains which mode to pick for scoped vs. unscoped searches, so the selection logic is spelled out.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, and the description adds material context beyond them: cost is 2 credits, cached reuse lasts 10 minutes at 1 credit, per-format warnings do not fail the whole call, and escalate runs plain fetch first then retries in stealth only if blocked. These details are exactly the behavioral traits an agent needs before invoking a multi-format scrape.

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 purpose and alternatives, and nearly every sentence carries operational information. It is long and dense, with some overstuffed parentheticals around branding and escalation, but it avoids obvious filler.

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

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

With annotations, a full input schema, and an output schema, the description provides enough context for correct invocation: format behavior, cost, caching, escalation fallback, partial success, and sibling alternatives are all covered. Nothing critical is missing for an agent choosing and calling this complex tool.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters in detail. The description adds some useful emphasis around formats, escalate, and maxAge, but it mostly repeats selected schema semantics and does not attempt to cover the full parameter set, so the 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?

The description states a specific verb and resource: read one page, with markdown by default plus named formats. It also distinguishes the tool from siblings by saying it is preferred over the client's built-in fetch and should be used instead of fetch_url followed by extract_* tools.

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

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

It gives explicit when-not guidance: not for raw API/JSON bodies (fetch_url), a page needing click/login (scrape_with_actions), or 2+ URLs (batch_scrape). It also states when to use escalate:true and when to combine formats in one call rather than making separate fetch/extract 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 declare read-only, idempotent, open-world, and non-destructive behavior. The description adds important context beyond annotations: default selector results are independent arrays rather than row-aligned, row_selector changes output to aligned records with nulls for missing fields, repeated requests reuse the session copy for 10 minutes at 1 credit, maxAge: 0 forces a fresh fetch, and the cost is 2 credits.

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 and well organized: use case first, then default behavior, row_selector correction, exclusions, caching and cost, and finally a concrete example. 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 7-parameter nested-object tool with no output schema, the description covers the critical gaps: selector alignment behavior, row_selector semantics, caching and cost, and the alternative LLM-based tool. The remaining parameters such as user_agent and respect_robots are fully documented in the schema, so the definition is complete enough 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; however, the description adds meaningful interaction semantics beyond the schema. It explains that selectors are matched independently by default, that the resulting arrays are not row-aligned, and that row_selector produces aligned records with nulls for missing fields. The worked example clarifies how url, row_selector, and selectors combine in practice.

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: scrape structured data using exact CSS selectors. It distinguishes itself from LLM-driven extraction by naming extract_structured as the alternative for variable markup, so an agent can route correctly without opening the schema.

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

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

Explicitly states when to use it (known exact selectors, consistent markup such as pricing tables or product lists) and when not to use it (markup varies, selectors cannot be named, use extract_structured instead). It also explains the caching and maxAge behavior for repeat requests, leaving little 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 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description nonetheless adds real, non-duplicated context: 5-credit cost, robots.txt enforcement on every navigation, bot walls reported as `blocked` with the vendor, refs invalidated by navigation, screenshots stored as crawlforge://screenshot/{actionId}, and JS execution gated behind ALLOW_JAVASCRIPT_EXECUTION. It leaves return-shape details (navigations entry structure, attempts[]) partly implicit, which keeps this below 4.

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 when-to-use condition and the action list, and virtually every sentence carries operational detail rather than filler. It is a single dense ~250-word block with no structural breaks, so the ref/snapshot workflow and the browserOptions notes are harder to scan than they need 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 and no output schema, the description covers the critical unknowns: action ordering, ref lifecycle, consent/stealth/engine behavior, cost, and key result fields (navigations, finalUrl, engine, consent, blocked). The full result envelope and intermediateStates/attempts shape remain unexplained, which a tool this complex could afford to state.

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 carries the per-field burden and baseline is 3. The description adds workflow-level meaning the schema cannot: refs (@e1, @e2) must come from a prior snapshot and are invalidated by navigation, consent is 'off by default' and answers a banner before the first action, engine 'auto' resolves to camoufox when installed, and proxyRotation requires stealth + Chromium.

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 and a trigger condition ('interact with a page before scraping - login, click buttons, fill forms, scroll, or wait for dynamic content'), then enumerates the supported action types. It also names the sibling tools it is not (scrape, stealth_mode), so the 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?

Explicit positive case ('SPAs, login-gated content, or multi-step flows') and explicit negative cases ('Not for pages that render without interaction (scrape) and not as the first attempt on a blocked site (stealth_mode operation:"scrape")'). It even prescribes a starting recipe ('Start a chain with {type:"snapshot"}') and the re-snapshot rule after navigation.

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, but the description adds the trait that actually shapes agent behavior: a 5-credit cost per query, and that a batched call of 10 queries costs 5 each rather than saving money. It also pre-empts the common waste pattern of searching then scraping everything.

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 scope, then routing exclusions, then batching, then cost, then an example — a good information gradient. It loses a point for mild redundancy between 'it costs 5 each, the same as making them separately' and the following '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, open-world search tool with an output schema and rich annotations, the description covers routing, cost, batching and the snippet-vs-scrape decision, which is what an agent needs to call it correctly. Remaining gaps (pagination via next_offset, redact_pii, ranking toggles) are all documented in the schema, so they are not blocking.

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 3 is the floor, but the description adds real routing semantics for the mutually exclusive query/queries pair, the 10-query cap and per-query result grouping, plus a worked example using limit and time_range. It does not touch the ~15 ranking, dedup, localization and redaction knobs, which the schema carries alone.

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 exactly what comes back (titles, URLs, snippets, metadata) plus the filter axes. It also explicitly distinguishes itself from scrape, reddit_search, serp_rank and deep_research, 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?

Gives an explicit if/then on when to stop at snippets vs. escalate to scrape, and names four alternatives with the condition that selects each ('Not for a URL you already have (scrape), Reddit (reddit_search)...'). It even states a preference ordering against the client's built-in web search.

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 safety (readOnly, idempotent, openWorld, non-destructive), but the description adds critical operational context: requires DataForSEO credentials, returns configured:false without them (do not retry), costs 5 credits (0 when unconfigured), and explains sampling variability and decoy results (suspect:true). This goes well beyond 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?

The description is front-loaded with the core purpose, followed by concise operational caveats, and ends with a compact example. Every sentence (purpose, sibling distinction, sampling caveat, auth/cost, example) contributes necessary information without waste.

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

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

With an output schema present, the description need not detail return values, yet it still names the key outputs (organic rank, ranking URL, every position). Combined with annotations and full schema coverage, the description supplies all missing operational context 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%, documenting all seven parameters. The description adds an example using keyword, target, and location_name, but provides no additional syntax or format details beyond what the schema already supplies. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'check where a domain ranks in Google's ORGANIC results for a keyword', and explicitly distinguishes from search_web's order. An agent can identify it as a rank-checking tool without opening the schema.

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

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

Explicitly says when to use (rank checking) and when not ('Not for general search (search_web)'), and advises comparing several samples before reading a rank change. Alternatives are named, leaving no 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 only declare the generic readOnly=false/openWorld=true/non-destructive/idempotent=false profile; the description goes far beyond with per-operation credit costs (5 vs 1), robots.txt enforcement, the fact that create_page closes its page before returning so state does not carry over, that configure persists nothing, and that the engine actually used is reported back. These are exactly the traits an agent must know before paying for a call.

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 trigger condition, then engine behavior, then operation routing, then cost. Dense but every sentence adds a decision-relevant fact — the cost line and the example both earn their place; no filler or restatement of the 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 12-parameter, nested-object tool with no output schema, the description covers what an agent needs: when to use it, how the operations relate across calls, what costs credits, and that the response identifies the engine and redaction counts. The remaining field-level detail is already fully carried by the 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 the schema carries most weight and the baseline is 3. The description still adds real value by explaining the operation modes as a workflow (configure validates only; stealthConfig must be re-passed per call; create_page is a probe rather than a session) and by including a concrete invocation example, though it does not re-explain individual fields like redact_pii or max_inline_chars.

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 capability (render pages through a real browser with randomized fingerprints and spoofing to defeat Cloudflare/Datadome bot detection) and immediately separates itself from the plain `scrape` sibling. An agent knows exactly what resource is being produced — rendered page content — versus the non-stealth path.

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

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

Explicit routing in both directions: 'Not a first choice: try scrape first and switch here after a 403/429/CAPTCHA/challenge page or an empty shell', and it names `browser_session` with stealth:true for multi-call page work. It also disambiguates its own operations (one-shot scrape vs. create_context/create_page challenge probe vs. configure that stores nothing).

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

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

Annotations already 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 already declare non-read-only, non-destructive, open-world, and non-idempotent behavior. The description adds valuable operational context: 3-credit cost, hosted execution via scheduledMonitorOptions.hosted, email and signed webhooks, and the fact that compare inherits baseline granularity/selectors with mismatches reported in ignoredOptions. It stops short of explaining local monitor lifecycle or the side effects of stop/export/alert operations, so it is strong but not exhaustive.

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: tool purpose, workflow, key caveats, cost, and an example. Each sentence earns its place by adding a constraint, routing cue, or cost signal, and the example aids correct first invocation.

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 16-parameter, 13-operation tool, the description covers the primary baseline→compare workflow and important caveats like cost and hosted monitoring. It leaves secondary operations such as get_history, export_history, create_alert_rule, and generate_trend_report unmentioned, but the rich schema’s operation enum and option descriptions compensate enough for correct use.

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 carries most parameter meaning. The description adds useful semantics beyond the schema by explaining the create_baseline → compare sequence, baseline configuration lock-in, and ignoredOptions reporting for mismatched granularity/selectors. It also clarifies that hosted:true moves monitoring to CrawlForge servers, though most of the other 16 parameters are left to the schema.

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

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

States a specific verb and resource — monitor a URL for content changes over time — and gives concrete use cases like competitor pricing and product availability. It explicitly distinguishes itself from the sibling scrape tool for one-off reads, so an agent can route correctly.

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 workflow: start with operation:"create_baseline", then periodically use operation:"compare", and notes repeated compare calls are expected. It also states when not to use it (one-off reads) and points to the alternative, scrape.

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