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 reasonably well: it discloses that the operation is asynchronous, returns immediately with a batch_id rather than results, and that results must be polled from GET /api/v1/batch/{batch_id}. Gaps remain around partial-failure behavior, cost implications, and rate limits for a 100-URL job.

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?

Four sentences, front-loaded with the core action and scope, then usage trigger, then per-URL nuance, then return semantics. No filler and nothing redundant given 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 async tool with 8 params, heavy nesting, and no output schema, the description covers the essential lifecycle (submit → get batch_id → poll). It is incomplete on how to retrieve results with the sibling status tool, what a completed batch payload looks like, and any webhook/export caveats beyond what the schema already says.

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 8 top-level parameters and the deeply nested per-URL options. The description adds only that per-URL mode, formats, and extraction_schema are honored independently, which is marginally useful but largely restates the schema structure. 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 and resource ('Start an asynchronous batch job for a large URL set') plus a scope cap (up to 100 per call) and the return shape (batch_id). It does not, however, distinguish itself from the sibling alterlab_batch_scrape, which sounds functionally identical, so the agent cannot disambiguate from the description alone.

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 an explicit trigger condition — use when a normal fetch returns 403/429, a bot-protection page, a CAPTCHA, or an empty JS shell — which is real usage guidance. But it never names an alternative tool, gives no when-not conditions, and offers no routing between this tool, alterlab_batch_scrape, and alterlab_batch_status.

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 supplied, so the description must carry behavior, and it does disclose the key traits: fully synchronous execution with no polling, and per-URL error containment so one failure does not abort the batch. It omits auth requirements, rate limits, and cost behavior beyond what the schema already states.

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?

Four short sentences, front-loaded with the core capability, then trigger conditions, then return semantics, then the escape hatch to the sibling. No filler sentences.

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 tool with no annotations and no output schema, the description covers execution model, failure handling, and tool selection adequately. It could say more about the shape of the aggregated response (e.g. result ordering or whether errors are inline per URL), which matters for a batch call.

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

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

Schema description coverage is 100% and the parameters are self-documenting, so baseline is 3. The description reinforces parallelism but does not explain formats, timeout, or proxy trade-offs beyond the schema, and its '2-20 URLs' range slightly conflicts with the schema's minItems of 1.

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 URLs) plus the defining scope: parallel, synchronous, 2-20 URLs, no polling. It differentiates itself from the sibling alterlab_batch by count threshold, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use triggers (403/429, bot-protection challenge, CAPTCHA, empty JS shell) and names the alternative for the out-of-scope case (20+ URLs → alterlab_batch). Both the selection condition and the exclusion 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?

With no annotations, the description carries the full burden and delivers the single most important behavioral fact: it is asynchronous, returning a crawl_id immediately with results fetched from GET /api/v1/crawl/{crawl_id} — which changes how an agent must sequence follow-up calls (likely to alterlab_crawl_status). It also discloses anti-bot/JS handling across all pages. It omits cost/politeness implications and that the job can be cancelled, which keeps it short of a 5.

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

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

Three tight sentences with zero filler: purpose and use cases first, sibling routing second, operational return contract last. Appropriate size for a 35-parameter tool and front-loaded with the scope constraint.

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 very complex, high-parameter, async tool with no annotations and no output schema, the description covers the essentials: what it produces, async polling contract, and scope. Remaining gaps (cost tier behavior, robots.txt default, cancellation) are all documented in the schema or handled by sibling tools such as alterlab_crawl_status and alterlab_crawl_cancel.

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% across all 35 parameters, so the schema already documents url, budget, cost_controls, extraction, and the rest in detail. The description adds no parameter-level meaning beyond the implicit note that anti-bot handling applies per page. Baseline 3 is correct when the schema does this much work.

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 ('Crawl a whole website and return the content of every page') plus the intended use cases (RAG, indexing, site-wide export). It explicitly distinguishes itself from alterlab_scrape (one URL) and alterlab_map (URL list only), so an agent can route between the three 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 ('many pages from one domain') and when-not-to-use, naming both alternatives and the conditions that select them. This is textbook sibling routing.

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 supplied, the description carries the full behavioral burden. It usefully discloses that nothing is billed and that the return carries tier, cost and confidence, but it says nothing about auth requirements for the tool itself, rate limits, or whether the estimate can diverge from the actual charge beyond the heuristic caveat buried 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?

Four short sentences, front-loaded with the purpose and the safety fact, then the return shape, then an escape hatch to the public pricing endpoint. Nothing is redundant with the schema or the title.

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 tool with no annotations and no output schema, the description covers purpose, cost safety, and the shape of the response. What is missing is the unit/naming of the returned cost figure and whether the estimate is authoritative, but the core calling decisions are covered.

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

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

Schema description coverage is 100% and each parameter already documents its own cost impact (POST 1.5x, render_js forces Tier 4, add-on prices), so the description adds no parameter meaning of its own. The baseline 3 applies: the schema does all the heavy lifting.

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

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

States a specific verb (estimate) and resource (credit cost of scraping a URL) plus the ordering constraint 'before you run it', which distinguishes it from the sibling alterlab_scrape. An agent can tell immediately this is a dry-run pricing tool rather than an execution tool.

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 trigger ('when cost matters or before a large job') and the key reassurance 'no credits are charged', which is exactly the condition an agent needs to decide whether it is safe to call. It does not explicitly name a sibling alternative, so it stops short of a 5.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose the key behavioral boundary (no URL fetching, bring-your-own content) and that output is JSON. It omits operationally important traits: that extraction is billed at an LLM rate unless a schema is supplied, that a BYOK provider key is required, and that results are cached by default.

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

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

Two tight sentences, front-loaded with the purpose and output type, followed by the usage rule and the negative boundary. No filler or 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?

For a 13-parameter, nested-schema tool with no output schema, the description still communicates the essential contract and routes to the correct sibling. The remaining gap is that nothing warns about LLM cost, BYOK key dependency, or default caching, which an agent calling this blindly could get wrong.

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

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

Schema description coverage is 100% and the 13 parameters are richly documented (cache modes, TTL, provider, profile/template aliasing, evidence provenance). The description adds essentially nothing beyond the schema, so the baseline 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?

States a specific verb and resource ('Extract structured data ... as JSON from HTML, text or markdown') with concrete example field types, and explicitly contrasts itself with the fetching sibling. An agent can distinguish it from alterlab_scrape immediately.

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 use condition ('Use when you have content and need specific fields'), an explicit exclusion ('Does not fetch a URL'), and names the alternative tool plus its parameter (alterlab_scrape with extraction_schema) for the fetch-and-extract 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?

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?

No annotations are supplied, so the description carries the full behavioral burden. It does disclose a meaningful trait — no page content is fetched — and hints at resilience on "JavaScript-heavy and protected sites," but it says nothing about robots.txt defaults, rate limits, URL caps, or what the result set looks like. There is also no output schema to cover the return format.

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 tight sentences with zero filler; the core action is front-loaded and the routing advice follows immediately. Every clause carries 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 an 11-parameter discovery tool with no annotations and no output schema, the description covers purpose, ordering relative to siblings, and the key no-content-fetch behavior. It stops short of describing the returned URL structure or default limits, which is a minor gap given the fully documented 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 (search ranking, sitemap modes, depth, patterns, subdomains) are already documented in the schema. The description adds only the high-level notion of sitemap parsing plus link extraction and does not clarify interactions between parameters. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb+resource ("List every URL on a site") and the mechanism ("sitemap parsing and link extraction"), plus an explicit scope boundary ("without fetching page content"). An agent can immediately distinguish this from alterlab_crawl, which it names 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?

It gives sequencing guidance ("Use before alterlab_crawl or alterlab_batch to choose pages") and names the alternative for the other job ("to read the content itself use alterlab_crawl"). The when-to-use / when-not-to-use split is stated outright 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, 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 supplied, the description carries the burden and does substantial work: it discloses the 5-tier escalation model ('starts at the cheapest tier that works and escalates only when needed'), the default output format, and the shape of the returned action_results array with per-action fields. It does not mention the async path (early 202 with job_id) or failure behavior, both of which matter for a tool this expensive to run.

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 correctly: purpose first, then the trigger condition, then capability summary. Five dense sentences with no filler. The final sentence on action_results is somewhat captured by the schema, but it earns its place as a return-value cue given there is no output 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 60-parameter tool with no annotations and no output schema, the description covers the main happy path but skips significant surface area an agent would need: the async job flow, session/auth reuse via session_id, caching/force_refresh interaction, and error semantics. It is adequate to make a first call correctly, not adequate to use the tool well across its full feature set.

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 60 parameters, including tier costs, mutually exclusive extraction options, and action types. The description only names clusters (method, extraction_schema/extraction_prompt, cost_controls, actions, screenshot, generate_pdf) without adding interpretation. That is the definition of the baseline case: helpful as orientation, but redundant with the schema.

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

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

Opens with a concrete verb and resource plus the return formats: 'Fetch one URL and return its content as clean markdown, text, HTML, or JSON.' The scope (single URL, multi-format) is unambiguous. It stops short of the top score because it never names the adjacent tools (alterlab_crawl, alterlab_extract, alterlab_batch_scrape) that an agent must choose between.

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 sharp trigger condition: use when a normal fetch returns 403/429, a challenge page, a CAPTCHA, or an empty JS shell. That is a real decision rule an agent can apply. It lacks an explicit when-not clause and never points to alterlab_extract for pure structured extraction or alterlab_crawl for multi-page work, leaving sibling routing to inference.

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

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

With no annotations, the description carries the full burden and does good work on the rendering model ('real headless browser', anti-bot handling) and on operation ordering (actions run before capture). However, it never says what the response actually contains as an image (base64? URL? how large?), and it instructs the agent to 'pass actions' with 'action_results' returned — neither of which exists in the input schema, which would mislead an agent into a failed 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 and dense: purpose in sentence one, failure triggers in sentence two, timing and ordering after. The final sentence about actions/action_results is the only bloat, and it is also the one passage that is factually wrong about the tool's signature.

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 9 parameters, nested objects, no annotations and no output schema, the description should at minimum say what a caller receives back for the screenshot and note the auth/session options. It covers the tricky timing and anti-bot behavior well but leaves the return value, the cookie/session path, and the geo/proxy options entirely to the schema, and references a phantom actions parameter.

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

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

Schema coverage is 100%, so the baseline is 3, and the description mainly restates what the schema already documents for wait_for and wait_until. Worse, the only parameter-level detail it adds — the 'actions' object and 'action_results' return — is not in the schema at all (additionalProperties: false), so it adds noise rather than meaning, while cookies, session_id, location, proxy_country and timeout get no coverage in the 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?

States a concrete verb and resource — capture a full-page PNG screenshot of one URL — and immediately disambiguates output type ('an image rather than text content'), which separates it from text-returning siblings like alterlab_scrape and alterlab_extract. An agent can pick this 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?

Gives explicit triggering conditions: normal fetch returning 403/429, a bot-protection challenge, a CAPTCHA, or an empty JavaScript shell. That is a named alternative (plain fetch) plus the exact failure conditions that should route the agent here, with no guessing 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?

No annotations exist, so the description carries the full behavioral burden. It does disclose the return shape and that scrape_results=true fetches every result's page in one call, but says nothing about cost implications, rate limits, or failure behavior — notable gaps for a tool whose schema advertises per-engine and per-page billing. The workflow disclosure is useful but partial.

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 tight sentences, front-loaded with purpose then routing then modifiers, with zero filler. The final sentence on domain and time_range largely duplicates the schema and is the one line that does not fully earn its place.

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 annotations and no output schema, the description covers the core search-vs-scrape decision well. However it is silent on pagination, the extraction_schema/formats pair, cost tradeoffs between engines, and billing when scrape_results=true — meaningful gaps given the schema's breadth.

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 parameter documentation is already handled and 3 is the baseline. The description's mentions of domain and time_range only restate what the schema states more precisely (site: prefix, recency enum), adding no new semantics beyond the scrape_results workflow pointer.

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 ('Search the web') and immediately specifies the return shape (URLs, titles, snippets). It explicitly contrasts with the sibling alterlab_scrape ('no URL yet... follow up with alterlab_scrape'), so an agent can route between search and scrape without inspecting 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?

Names the selecting condition ('when you have a question or topic but no URL yet') and the alternative to use otherwise, plus a second mode (scrape_results=true) that bypasses a separate scrape call. Both the when-to-use and the escalation path are 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, 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.