alterlab-mcp-server

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

With no annotations, the description carries the full burden and does so well: it discloses that the call is asynchronous (returns batch_id immediately, poll later), the tiered per-URL pricing model, automatic anti-bot bypass, and the credit pre-debit/refund lifecycle. That is a rich, non-obvious behavioral profile an agent needs to plan the workflow.

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 sibling comparison are front-loaded, then cost, async behavior, and scoping follow in a logical order. It is dense but every sentence carries operational information; about seven sentences is on the heavier side for a description whose schema already documents everything.

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-parameter tool with deep nested objects, no annotations and no output schema, the description covers purpose, triggering condition, async return, cost mechanics and result retrieval path. It does not detail failure/partial-success handling of the batch, which is the main remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine scoping semantics the schema does not state in one place: which settings are per-URL (mode, method/body, formats, extraction, advanced, location, cost_controls) vs batch-level (session_id, extraction_*, export). This prevents mis-nesting of options.

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 with scope: 'Scrape up to 100 URLs in parallel with a single request.' It explicitly distinguishes itself from the sequential sibling alterlab_scrape, so an agent can choose between them 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 a concrete decision threshold ('use this whenever you need to scrape more than 2-3 URLs') and names the exact follow-up tool (alterlab_batch_status) for polling. It does not, however, disambiguate itself from the other similarly-named sibling alterlab_batch_scrape, which is a real selection risk.

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?

With no annotations, the description carries the full burden and does well: it discloses synchronous no-polling behavior, concurrent scraping via max_concurrent, graceful partial-failure handling, and what a call returns (per-URL status, preview, cost summary). It omits permission/auth requirements and any rate-limit behavior, which keeps it from a 5.

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

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

Front-loads the key differentiator (synchronous, no polling) in the first sentence and keeps each subsequent sentence purposeful. Slightly longer than necessary — the cost-summary and preview details could be trimmed — but 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?

No output schema exists, so the description must cover return values, and it does: per-URL status, content preview, error details on failure, and a total cost summary. Auth/permission prerequisites are the main remaining gap for a paid scraping endpoint.

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 six parameters, including defaults and ranges. The description adds only a light gloss on max_concurrent ('controlled by max_concurrent') and return behavior, so the baseline 3 applies.

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

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

States a specific verb (scrape) and resource (multiple URLs) and immediately distinguishes itself from the sibling alterlab_batch by contrasting synchronous inline return vs async batch_id polling. An agent can tell these two tools apart 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?

Explicit routing: best for 2-20 URLs needing immediate results, and 'For 20+ URLs, use alterlab_batch instead.' Both the when and the when-not, with a named alternative, are stated.

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 return behavior with status values and when results are returned. No annotations are provided, so the description carries the burden; it covers the key behaviors for a polling tool, though it doesn't explicitly state non-destructiveness.

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

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

Three short sentences that are well-structured, front-loading the purpose and then providing status values and results. No redundancy.

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?

Adequately covers usage, status values, and result content. No output schema, but the description explains what to expect. For a simple polling tool with one parameter, this is sufficiently complete.

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?

Only one parameter (batch_id) with 100% schema description coverage. The tool description reinforces that the batch_id comes from alterlab_batch, but adds no new semantic detail 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?

The description clearly states the action (poll) and resource (status and results of a submitted batch), and it distinguishes from siblings by specifying that this is to be used after alterlab_batch.

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

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

Explicitly says to call after alterlab_batch, providing clear usage context. Does not mention when not to use or alternatives, but the context is clear enough.

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?

Describes exactly what is returned (balance, status, deposited, spent) and notes that no parameters are required, using API key for identification. No annotations exist, so description fully covers behavioral traits.

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

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

Two sentences with no wasted words, front-loaded with purpose, and includes a tip and an alternative reference.

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 no output schema, the description fully explains return values and provides context about when to use and alternative tools, making it complete for the tool's complexity.

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?

No parameters in schema, and the description explicitly states 'No parameters required — uses your API key for identification,' adding 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 clearly states the tool checks account balance, status, and credit usage. It distinguishes from sibling alterlab_get_usage by noting that tool provides a full spending breakdown.

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 advises calling before expensive operations like batch scrapes or large crawls. Also provides an alternative tool (alterlab_get_usage) for detailed breakdown, giving both when-to-use and when-not-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?

No annotations are provided, so the description carries the full burden, and it delivers substantial behavioral context: anti-bot/Cloudflare bypass, asynchronous per-page scraping, immediate crawl_id return with polling requirement, tiered per-page billing with an actual price ladder, and cost-control semantics. It omits auth/permission requirements and what happens on partial failure, so it falls short of fully self-describing.

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 sentence, then a tight sequence of feature-specific sentences, each covering a distinct capability. It is necessarily long for 35 parameters and every sentence earns its place, though the single dense paragraph with many repeated 'Use X' clauses is harder to scan than a structured list would 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?

With no output schema, the description correctly covers returns: markdown/text/structured content and an immediate crawl_id for polling. It also documents billing and major option groups, so the agent has what it needs to call the tool. Minor gaps remain around auth requirements and the exact shape of change-tracking/webhook outputs.

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 already 100%, so the baseline is 3, but the description adds genuine usage meaning beyond it: budget as per-path allocation, render_js='auto' saving 30-60%, cost_controls tiers, headers injection (e.g. Authorization), sitemap_path for non-standard locations, and change_tracking/webhook behaviors. It stops short of documenting most parameters' syntax, so it is additive rather than exhaustive.

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 ('crawl') and scope ('an entire website'/'all pages on a site'), plus the concrete goals (RAG, indexing, knowledge base). The 'entire website' framing implicitly distinguishes it from the single-page alterlab_scrape sibling, so an agent can tell the two apart 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 clear use-case context and explicitly routes the agent to alterlab_crawl_status for polling, and repeatedly says when to use individual features (render_js='auto' for mixed sites, include/exclude_patterns to scope, cost_controls to cap spend). It does not, however, state when NOT to use this tool versus alterlab_scrape / alterlab_map / alterlab_batch_scrape, which is the main missing routing guidance for a 35-param primitive.

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?

With no annotations, description carries full burden. It discloses key behaviors: cancellation stops crawling, refunds credits, keeps already-scraped pages (via alterlab_crawl_status), and prohibits resumption. Sufficiently transparent for a simple cancellation tool, though auth or rate limits are not mentioned.

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

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

Two sentences, zero waste. First sentence captures primary action and refund. Second sentence adds important details about persistence and non-resumability. Efficient and front-loaded.

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

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

For a simple tool with one parameter and no output schema or annotations, the description fully covers what the tool does, what happens to scraped pages, and what cannot be done afterwards. No significant gaps.

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?

Only one parameter 'crawl_id' with schema coverage 100%. Description adds no extra meaning beyond the schema's 'Crawl ID to cancel'. Baseline 3 is appropriate as schema already documents the parameter.

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?

Description clearly states verb 'cancel', resource 'ongoing crawl', and additional action 'refund unused pre-debited credits'. Distinguishes from sibling tools like alterlab_crawl and alterlab_crawl_status by specifying cancellation and refund behavior.

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?

Description implies when to use (to stop a crawl) and notes that cancelled crawls cannot be resumed, but does not explicitly state when not to use or mention alternative tools. Provides context about already-scraped pages but lacks exclusions.

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

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

No annotations provided, so description carries full burden. It explains polling behavior and that results are present when completed, but does not specify idempotency, whether results persist after first read, or any side effects. Adequate but not deep.

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

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

Two sentences with no wasted words. Front-loaded with purpose, then adds details on status values and output. Excellent conciseness.

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, so description explains that 'results contains the scraped page content' when completed. Lists status values. Could mention if results are paginated or size limits, but complete enough for a simple status poll 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 coverage is 100%, so baseline 3. Description adds context by noting crawl_id is returned by alterlab_crawl, helping the agent understand the parameter source. Slight improvement over bare 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?

Description clearly states it polls status and results of a crawl, explicitly naming the action and resource. It distinguishes itself from siblings like alterlab_crawl and alterlab_crawl_cancel by specifying it is the follow-up call for progress checking.

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 'Call this after alterlab_crawl' and lists status values, providing clear context. Does not include explicit when-not-to-use or alternative tools, but given sibling set, this is the only status poll for crawls.

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?

With no annotations, the description carries the full load and does it well: it discloses that cookies are stored securely, that the session is reusable via session_id, that consent=true is mandatory (API rejects with CONSENT_REQUIRED), and that org sharing and auto-refresh/notification flags exist. It doesn't cover what happens on failed validation beyond the notify flag, but this is solid behavioral context for a mutation 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?

Three sentences, front-loaded with the core action and the login-wall use case before prerequisites. The final sentence is a somewhat dense enumeration of optional parameters, but nothing is wasted and it remains scannable.

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 mutation tool with no annotations and no output schema, the description covers purpose, prerequisites, consent semantics, and reusability. It implies the returned session_id but doesn't explicitly state what the caller gets back or any failure modes beyond consent — a minor gap, though no output schema exists to fill it.

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

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

Schema description coverage is 100%, so all 12 parameters (including nested cookie metadata and the important consent semantics) are already documented in the schema. The description echoes the consent requirement and enumerates optional features, adding orientation but no syntax or meaning beyond the schema — 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 opens with a specific verb+resource ('Create a new stored session') and immediately scopes it to authenticated scraping, which cleanly separates it from the session-management siblings (list/get/validate/update/refresh/delete). The purpose and the persistence model are unambiguous 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?

It states the trigger condition clearly: use this when you need to scrape behind login walls and can supply cookies from a logged-in browser session. It also surfaces the consent prerequisite. It stops short of naming explicit alternatives or when-not-to-use cases (e.g. using a one-off cookie header on alterlab_scrape instead), so it's strong but not complete 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?

Since no annotations are provided, the description carries full weight. It discloses that the deletion is permanent and removes cookies, which are critical behavioral traits. No contradictory or missing safety cues.

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

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

The description is two sentences long, front-loaded with the main action, and contains no superfluous words. Every sentence adds value: purpose and usage context.

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 tool with one parameter, no output schema, and no annotations, the description is complete. It covers action, effect, and appropriate use case, leaving no obvious gaps.

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

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

The input schema already fully describes the single parameter (session_id as a UUID). The description does not add new semantic information beyond the schema; it simply references the session. With 100% schema coverage, the baseline score 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 explicitly states 'Delete a stored session' and emphasizes permanence, distinguishing it from sibling session tools like create, get, update, or refresh. The verb 'delete' and resource 'session' are specific and 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?

Provides clear when-to-use guidance: 'Use this when a session is no longer needed or has been compromised.' This is explicit context, though it does not formally exclude alternatives. However, the purpose is sufficiently distinct from siblings.

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

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

With no annotations, the description carries the full burden. It discloses idempotency ('calling it when not opted in returns success') and the limitation on GA features. It does not mention side effects, auth needs, or error behavior, but the operation is simple enough that this is adequate.

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

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

The description is three sentences, front-loading the purpose, then adding idempotency and constraint. No wasted words.

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 tool with one parameter and no output schema, the description covers purpose, idempotency, and a constraint. It also references a sibling tool for listing slugs. Minor gaps: no mention of return values or error states, but overall adequate.

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

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

Schema coverage is 100% since the parameter 'slug' already has a description. The tool description adds no new semantic detail beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool's purpose: 'Opt out of a beta feature on your AlterLab account.' It uses a specific verb-resource pair and distinguishes from sibling tools like 'alterlab_enable_beta_feature' by noting that GA features cannot be disabled.

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 context by mentioning idempotency and the constraint that GA features cannot be disabled. It also directs users to 'alterlab_list_my_beta_features' to find valid slugs. However, it does not explicitly contrast with enabling or list all alternatives.

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?

With no annotations, the description mentions idempotency and experimental nature, but does not disclose potential side effects, permissions required, or reversibility (e.g., via 'alterlab_disable_beta_feature'). More behavioral context would be beneficial.

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 consists of two concise sentences with no wasted words. It front-loads the action and efficiently adds necessary context.

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

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

For a single-parameter tool with no output schema, the description adequately covers purpose, parameter guidance, and a related sibling. It could mention the response format, but it's not essential.

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

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

Schema coverage is 100% and the description adds value by providing an example slug format and referencing the list endpoint for discovery, going beyond the schema's minimal description.

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 action ('Opt in to a beta feature'), the resource ('AlterLab account'), and distinguishes it from siblings like 'disable_beta_feature' and 'list_beta_features'.

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 advises to use 'alterlab_list_beta_features' to discover available slugs, guiding when to use the tool. It does not explicitly state when not to use it, but the context is sufficient for a simple opt-in tool.

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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses that no credits are charged, that it returns a predicted anti-bot tier, cost, and confidence, and it enumerates the exact per-tier pricing and add-on effects on cost — the key behavior an agent needs to interpret results.

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 in the first clause, and every subsequent sentence (the tier price table, the options hint) is cost-relevant reference material, not padding. The price enumeration is dense but each line maps directly to behavior the caller must interpret.

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-param tool with no output schema and no annotations, the description compensates fully by naming the return fields (tier, cost, confidence) and the zero-charge guarantee, so an agent can invoke and interpret it without further context.

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 value beyond the schema by listing tier prices referenced by the option params and by instructing which params to use to see cost effects (render_js, use_proxy, screenshot, generate_pdf, ocr, method). It stops short of explaining each param's syntax, hence 4.

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

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

States a specific verb+resource+scope: 'Preview the cost of scraping a URL before committing — no credits charged.' It is immediately distinguishable from the many action siblings (alterlab_scrape, alterlab_batch_scrape, etc.) because it is explicitly a non-executing preview.

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 a clear when-to-use rule: 'Call this before scraping protected or unfamiliar sites to avoid surprises.' It does not state a when-not condition (e.g. no need for already-known cheap sites), but no competing estimate sibling exists, so the routing guidance is effectively complete.

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?

With no annotations, the description carries the full burden and does disclose key traits: it does not fetch URLs, it returns JSON data, and cache='only' never invokes the LLM. It does not mention auth/BYOK requirements or rate limits, but those are partially covered by the schema's extraction_provider description.

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

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

Front-loaded with the core purpose and the negative scope early, then terse routing sentences. Slightly redundant opening with three synonymous phrasings ('extract product data, scrape prices, get structured data'), but overall efficient.

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

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

For a 13-parameter tool with a nested extraction_schema and no output schema, the description covers the essential calling context: it must receive pre-fetched content, returns JSON, and lists available profiles. Minor gaps remain around provider/model selection behavior, but the schema covers those.

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 including profiles, cache modes, and evidence. The description restates profile contents ('product' (price, title, reviews)) and cache behavior already present in the schema, adding little new meaning beyond the scraping-vs-extraction distinction.

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?

Specific verb+resource with concrete examples of extractable fields (names, emails, ratings, prices), plus an explicit negative scope: 'Runs AlterLab's extraction pipeline on raw HTML, text, or markdown you already have — does NOT scrape a URL.' It clearly distinguishes itself from the alterlab_scrape sibling by naming it directly.

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 alternatives: 'For scraping + extraction in one step, use alterlab_scrape with extraction_schema instead,' plus routing guidance for extraction_prompt (natural language/LLM) and cache='only' (retrieve cached result without LLM). The conditions that select each path are stated, not implied.

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

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

With no annotations, the description carries the full burden and does disclose key behavioral traits: the polling cost model ('Polling is free'), the billing consequence of misuse, and the meaning of each terminal status, including 'rejected' due to insufficient balance. It does not cover permissions/auth or the shape of the returned result, leaving some gaps for an unannotated tool.

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

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

Front-loads the purpose, then the usage condition, then the status semantics and the cost warning. Every sentence earns its place 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?

No output schema exists, so the description compensates by enumerating the five status values and clarifying the terminal 'rejected' state. For a single-parameter polling tool, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and there is a single parameter, so the schema already documents job_id fully. The description still adds value by explaining the provenance of the ID (an async or downgraded scrape outliving the ~85s synchronous window), reinforcing the schema's own note.

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 the status and result of an asynchronous scrape job by job_id') and explicitly distinguishes itself from the siblings that generate jobs (alterlab_scrape, alterlab_screenshot). An agent can route correctly without opening any schema.

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

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

Gives an explicit trigger condition ('when alterlab_scrape or alterlab_screenshot returns a job_id instead of content') and a clear directive for the terminal case ('rejected ... stop polling and check the balance'). It also warns against the wrong action (do not re-run the scrape, which would be billed again), which is strong when-to/when-not 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?

No annotations provided, so description carries full burden. It describes the data returned (status, cookie names, usage stats, expiry, notes) and implies a read operation. It does not mention side effects, auth, or rate limits, but for a simple get operation this is adequate.

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

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

Two sentences: first states function and return, second gives usage guidance. No wasted words, front-loaded with key 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?

Given one required parameter, full schema coverage, no output schema, and clear sibling context (CRUD for sessions), the description fully covers what an agent needs to know to use this tool correctly.

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

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

Only one parameter (session_id) with 100% schema coverage (UUID format). The description adds context for why the parameter is needed ('inspect a session') beyond the schema, providing extra value.

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 'Get detailed information about a specific stored session' and lists specific return fields (status, cookie names, usage statistics, expiry info, notes). It distinguishes from sibling tools by saying 'inspect a session before deciding to validate, refresh, or delete it.'

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 'Use this to inspect a session before deciding to validate, refresh, or delete it.' This gives clear context for when to use. It doesn't explicitly exclude scenarios, but the guidance is strong.

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?

With no annotations, the description carries the full burden and does disclose the identification mechanism ('uses your API key') and the exact data returned, which is the main behavioral concern for a zero-argument read tool. It stops short of explicitly declaring the operation read-only or noting any rate limiting, 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?

Three front-loaded sentences: purpose and payload first, then the sibling routing rule, then the no-parameter/auth note. Every sentence adds information and none 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?

There is no output schema, and the description compensates by listing the returned fields. For a simple no-argument read tool with a named alternative, nothing an agent needs to call it correctly is missing.

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

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

The tool takes no parameters, so there is nothing to disambiguate; the description reinforces this with 'No parameters required.' Baseline for a zero-parameter tool is 4.

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 ('Get account usage for the current billing period') and enumerates the returned fields (balance, credits consumed, tier, entitlement source). It is clearly distinguishable from the sibling alterlab_check_balance, which is named explicitly.

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 usage rule: use this to track spend against the plan, and use alterlab_check_balance for deposit and spend totals. The selecting condition between the two sibling tools is stated rather than inferred.

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?

With no annotations, description transparently states it lists features and opt-in state, implying read-only behavior. Does not disclose performance or rate limits, but sufficient for safe use.

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

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

Two concise sentences, front-loaded with key action and result. No wasted words.

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 no parameters and no output schema, the description fully covers what the tool does and its output (list with opt-in state). Refers to sibling for next action.

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?

No parameters exist; schema coverage is 100%. Description adds nothing about parameters, but baseline 4 is appropriate for zero-parameter tools.

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 it lists all public beta and GA features with opt-in state, using specific verb 'list' and resource 'features'. It differentiates from sibling 'alterlab_enable_beta_feature' by mentioning that tool for opting in.

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 clear context: use to view features and opt-in state, and suggests 'alterlab_enable_beta_feature' for opting in. Does not explicitly contrast with 'alterlab_list_my_beta_features', but overall guidance is strong.

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?

No annotations provided; description reveals it is a read operation returning a compact slug list. Notes that list includes GA features and opted-in beta features. Lacks details on pagination or format but sufficient for a simple 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 with clear purpose: action, content, usage guidance. No redundant words; highly efficient.

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

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

For a parameterless, no-output-schema tool, description fully covers what it does, what it returns, and why to use it. Context with sibling tools is sufficient.

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

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

No parameters; schema coverage is 100% trivially. Description adds meaning by explaining the composition of the list (GA + opted-in beta features), which is beyond schema structure.

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?

Description clearly states verb 'list' and resource 'beta and GA features active on your account'. It differentiates from sibling 'alterlab_list_beta_features' by specifying scope is only active features on the user's account.

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: 'to verify which features are available before making API calls that require them'. Does not explicitly name alternatives but context implies use sibling for full list.

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?

With no annotations provided, the description carries the full burden. It clearly describes the read-only listing behavior ('List all stored sessions') and adds context about authenticated scraping. No side effects are mentioned, which is appropriate for a listing 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?

Two sentences, front-loaded with verb and resource, no filler. Every word adds value.

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 no parameters and no output schema, the description is complete enough. It explains the purpose of sessions (cookies, login) and the workflow with alterlab_scrape. A minor gap: no mention of return format or pagination, but for a list tool this is sufficient.

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

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

The input schema has no parameters (0 params, 100% coverage). The description adds no parameter info, which is acceptable since none exist. Baseline 4 for zero parameters.

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 'List all stored sessions for authenticated scraping' with a specific verb and resource. It distinguishes from sibling tools like alterlab_create_session, alterlab_delete_session, and alterlab_get_session.

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: to obtain session_id for alterlab_scrape. Implicitly excludes other operations (create, delete, get) via sibling names. Could add explicit when-not or alternatives.

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?

With no annotations, the description carries the full burden and does well: it discloses the cost model ($0.001 flat, up to 50,000 URLs), the exclusion of scraping/JS rendering, and the return shape (flat list with source and depth). It omits auth requirements and latency/politeness caveats beyond the robots parameter, so it falls just short of full behavioral coverage.

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

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

Front-loads purpose, then cost, then sequencing, then per-parameter hints, so an agent can stop reading early. It is longer than strictly necessary and repeats the sitemap_path example already in the schema, keeping it from a 5.

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

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

For an 11-parameter tool with no output schema, the description compensates by describing the return value (flat URL list with source and depth) plus cost and sequencing. The complete schema coverage handles the rest, leaving nothing an agent critically needs 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 description coverage is 100%, so the baseline is 3. The description adds workflow-level meaning beyond the schema, notably combining search ranking with pattern scoping and clarifying that include_patterns/exclude_patterns scope discovery to sections. This exceeds what the schema alone conveys, though some items (sitemap_path example) restate 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 ('discover all URLs on a website... get a sitemap') and explicitly bounds scope with 'no content scraping, no JS rendering'. It clearly distinguishes itself from alterlab_crawl and alterlab_batch, positioning itself as the discovery step that precedes them.

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

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

Gives explicit sequencing guidance ('Use this before alterlab_crawl or alterlab_batch to identify which pages to scrape') and names the alternatives by name. It also routes parameter-level choices conditionally (search to rank by relevance, include_metadata for titles/descriptions), so the agent knows when to reach for each behavior.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the mutation (cookie rotation), the side effect of resetting status to active, and the fallback behavior when cookies are omitted. It omits auth/permission requirements and reversibility, so not a full 5.

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

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

Three sentences, front-loaded with the core action, then usage context, then the edge-case behavior. No filler and each sentence adds distinct 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 3-param mutation tool with nested objects and no annotations or output schema, the description adequately conveys what changes and when. It could still note authentication prerequisites or what the refreshed session returns, keeping it short of 5.

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 three parameters (including the cookies conditional and format). The description largely restates the omit-cookies behavior that the schema already encodes, adding little beyond the 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 (refresh) and resource (session) and enumerates the concrete effects: rotating cookies, resetting failure counters, and setting status to active. The phrase 'preferred way to update cookies' implicitly distinguishes it from sibling tools like alterlab_update_session, letting an agent 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 a clear when-to-use trigger ('after re-authenticating in your browser') and the conditional path when cookies are omitted. It stops short of naming alternatives or explicit exclusions, so it clears the 4 bar but not the 5.

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

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

With no annotations, the description carries the full behavioral burden and delivers: tier escalation logic ('you only pay for the tier that succeeds'), a complete cost table, add-on pricing, mutation multipliers (POST = 1.5x), default return format, caching semantics, fail-fast vs auto-escalation behavior, and the server-side job_id continuation for long-running scrapes. This is exactly the beyond-schema behavioral disclosure the 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?

The purpose is front-loaded, which is good, but the body is an enormous wall of repetitive 'Use X to...' sentences that duplicate the schema line-for-line. For a 60-parameter tool some length is defensible, yet the majority of sentences restate structured data and do not earn their place, making the description a manual rather than a focused definition.

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 60-parameter, nested-schema tool with no output schema and no annotations, the description is nearly complete: it covers return format defaults (markdown), the format alternatives, async job_id handling, cost/tier behavior, auth paths, and caching. The only minor gap is a lack of clarity on the exact response envelope, but the return-shape essentials are present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates parameter documentation already present in the schema (method/POST, render_js tiers, formats, cost_controls) rather than adding new semantics. It does aggregate parameters into a readable workflow narrative and clarifies 'you only pay for the tier that succeeds,' but the net informational gain over the schema is marginal.

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

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

The opening sentence names a specific verb and resource — 'Get data from any website... scrape JavaScript-rendered pages... fetch content from dynamic single-page apps' — and the markdown-conversion scope is unmistakable. An agent can tell this is a single-page scrape tool. However, it never explicitly distinguishes itself from siblings like alterlab_batch_scrape, alterlab_crawl, or alterlab_search, so it stops short of a 5.

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

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

The description is saturated with 'Use X to do Y' parameter guidance (render_js, method, formats, prefer_cost, etc.), which gives strong intra-tool usage context. But it never addresses tool-level selection — when to choose this over alterlab_batch_scrape, alterlab_crawl, or alterlab_extract — and offers no 'when not to use' exclusions. Usage guidance is implied through capability statements rather than stated as routing criteria.

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?

With no annotations, the description carries the full burden and does well: it discloses anti-bot bypass coverage (Cloudflare, DataDome), the real headless browser, a full-page PNG return delivered in-conversation, and the exact tier-4 pricing ($0.004 + $0.0002). It does not cover failure behavior or rate limits, 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?

Front-loaded with the core purpose, then progressively details capabilities and parameters, ending with the sibling routing. Every sentence adds something, though the three synonymous opening phrasings and stacked param tips make it longer than strictly necessary.

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

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

With no output schema, the description supplies the return format (full-page PNG in conversation) and covers the main capability and pricing context. For a 9-parameter, nested-schema tool it could say more about geo/proxy interplay and timeout defaults, but nothing essential to a correct call 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 baseline is 3, but the description adds genuine usage meaning beyond the schema for wait_for, wait_until, session_id, and cookies (element gating, load-event choice, authentication). It stops short of documenting location/proxy_country/timeout interactions, keeping it at a 4.

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?

State a specific verb and resource ('Take a screenshot of any website') with three near-synonym phrasings that catch varied agent intents, and it explicitly distinguishes itself from alterlab_scrape by positioning that tool as the full-option fallback. An agent can tell what this does and how it differs from siblings 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 guidance for the key parameters ('Use wait_for to wait for a specific element', 'Use session_id or cookies to capture pages behind a login') and names the alternative for broader needs ('call alterlab_scrape with screenshot=true'). The routing to the sibling tool is unambiguous.

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

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

With no annotations present, the description carries the full burden and does so well: it discloses per-engine pricing tiers ($0.001 vs $0.004), that scrape_results incurs additional per-page scraping-tier billing, multi-engine failover for reliability, anti-bot bypass, and that safe search is on by default. Cost and default behavior are exactly the traits an agent needs before invoking a paid API.

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

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

It is a dense paragraph, but front-loaded with purpose and output shape before moving to cost and parameter guidance. Nearly every sentence carries information, though the repeated cost figures slightly overlap the engine parameter description 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 a 12-parameter tool with no output schema and no annotations, the description covers the response shape, cost model, and the most consequential optional parameters. It is a bit thin on how scrape_results interacts with formats/extraction_schema and says nothing about pagination beyond what the schema already states.

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 every parameter, giving a baseline of 3. The description restates a few key ones (domain as site:, time_range, engine cost differences) but adds no syntax or format detail beyond the schema, and omits extraction_schema and formats 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?

The opening sentence states a clear verb+resource ('Search the web... research a subject across the internet') and the second states the return shape (URLs, titles, snippets from multiple engines). It is distinguishable from siblings like alterlab_scrape or alterlab_extract, which retrieve page content rather than ranked results.

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 concrete when-to-use guidance for specific parameters: domain for site restriction, time_range for recency, scrape_results to fetch full page content, and engine selection driven by cost. It does not, however, explicitly say when to prefer this over alterlab_scrape or alterlab_extract, nor when not to use it.

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?

With no annotations, the description carries the full behavioral burden. It does add one genuinely important destructive trait — cookies 'replace ALL existing cookies (not merged)' — which an agent must know. However, it says nothing about permissions, whether the update is partial, the fate of unspecified headers, or reversibility, so the disclosure is helpful but incomplete.

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

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

Three short sentences, front-loaded with the purpose, then the mutable fields, then the critical replace-semantics caveat and the usage recommendation. Every sentence earns its place 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 9-parameter mutation tool with no annotations and no output schema, the description omits the notification/auto-refresh/health-check parameters entirely and never states whether the operation is partial or full-replace across all fields. The cookie caveat helps, but enough behavioral context is missing that it is only minimally adequate.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters, including the cookie replace-all semantics and the notification/auto-refresh booleans. The description restates a subset of fields (name, notes, headers, expiration) without adding format or constraint detail beyond the schema, so baseline 3 applies.

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

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

Specific verb (update) plus resource (stored session) with an enumerated list of mutable properties (name, cookies, headers, expiration, notes). It distinguishes itself from the delete+recreate pattern and is clearly separable from siblings like get_session, list_sessions, or refresh_session.

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 a concrete when-to-use rule: 'Use this instead of delete+recreate when you need to rotate credentials.' That is stronger than implied usage, but it never mentions the closely related refresh_session or create_session siblings, so routing among the session-lifecycle tools is only partially resolved.

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 that it checks session activity and cookie validity, returns status and reason if invalid. No annotations provided, so description carries burden; no side effects mentioned but validation is inherently read-only.

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

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

Two sentences, front-loaded with the main action, no wasted words.

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?

Adequately covers purpose, usage context, and return information for a simple validation tool with one parameter and 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?

Only one parameter (session_id) with 100% schema description coverage. The description does not add meaningful detail beyond what the schema already provides (UUID for session). Baseline score of 3 applies.

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

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

Clearly states validation of session activity and cookie validity. Distinguishes from sibling tools like create, delete, refresh, get by focusing solely on checking status.

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 'Run this before scraping if you suspect a session may have expired,' providing clear context for use. No explicit exclusions but implied.

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