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

The annotations already declare readOnlyHint and idempotentHint, and the description adds useful behavioral context by explaining the mechanism for idempotency ('stable content-hash ids') and the chunking/overlap behavior. It does not go into edge cases or failure modes, but the combination of annotations and description is solid.

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, highly informative, front-loaded with the core transformation, and no filler. Every clause adds meaning: input, output, chunking, idempotency, metadata, pagination.

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

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

Given the tool's complexity (9 parameters, transformation, output schema exists), the description covers the main operational aspects: chunking, overlap, idempotency, metadata, and pagination. It leaves some ambiguity about 'selected metadata' and exact chunking behavior, but the output schema and annotations fill in enough 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?

Schema description coverage is only 33%, so the description must compensate. It does explain the purpose of chunking, overlap, metadata selection, and pagination, but it does not explicitly map these to parameter names, and parameters like max_response_tokens and format are left to the reader's inference. This is useful but not complete compensation.

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

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

The description clearly states a specific verb+resource transformation: 'Turn scraped items into embedding-ready documents'. It enumerates distinct output characteristics (token-bounded chunks, overlap, source attribution, content-hash ids, metadata) that clearly differentiate it from sibling tools like fetch_dataset_items or validate_dataset.

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 clear context for when to use the tool: after scraping, before embedding, and it advises pagination for large datasets. However, it does not explicitly name alternatives or state when not to use it, so it misses the explicit exclusion guidance that would earn a 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds valuable behavioral details: response format (JSON in text content, pagination metadata in structured content), hard token budget, and pagination behavior. No contradiction with annotations.

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

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

Three concise sentences, front-loaded with main purpose, followed by actionable tips and return format. Every sentence earns its place; no fluff.

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?

Tool has an output schema and the description covers the workflow, pagination metadata, and return format. It is complete for the complexity level, though it could briefly mention the dataset_id requirement. Still, the description is adequate and well-rounded.

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 50%, and description compensates by explaining key parameter usage: response_format ('summary' vs 'items'), fields projection, token budget, and pagination. It adds strategic meaning beyond schema definitions, though limit/offset/max_tokens lack explicit descriptions.

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

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

Description uses specific verb 'Read' + resource 'items from an actor run dataset', clearly distinguishing it from siblings like run_actor (executes) and get_run_status (status). The scope is unambiguous and action-oriented.

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

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

Provides explicit workflow guidance: 'Start with response_format summary... then fetch items with a fields projection.' This is clear practical usage context. However, it lacks explicit when-not-to-use or alternative tool comparisons, so not a full 5.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds value by specifying 'Free and safe to poll' and disclosing that the response includes dataset location. This goes beyond the structured annotations without contradicting them.

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

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

The description is two short sentences, front-loaded with the core purpose, and contains no filler. Every word contributes to understanding the tool's function and safety.

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 status-checking tool with one parameter, rich annotations, and an output schema, the description is complete. It states what the tool does, what information it provides, and that it is safe to poll, fully covering the essential 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?

The schema already provides 100% coverage for the single parameter (run_id) with a helpful description. The tool description adds no additional parameter meaning, so the baseline of 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 clearly states the tool's function: 'Check whether an actor run has finished and where its dataset is.' This is a specific verb+resource statement that distinguishes it from siblings like run_actor or fetch_dataset_items, which handle running or retrieving data.

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 clear context: it is for checking run completion and locating the dataset, implying use after triggering a run. It also notes it is 'free and safe to poll,' indicating suitability for repeated use. However, it does not explicitly mention when not to use it or name alternative tools for other purposes.

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

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

The description discloses significant behavioral details beyond annotations: progressive anti-blocking escalation (residential proxies, then browser crawler), termination after threshold or exhausting attempts, and that each attempt costs credits. Annotations only note non-read-only and non-destructive, lacking these important operational details.

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

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

The description is two sentences, front-loaded with the action and key mechanism, and ends with a critical cost warning. Every word earns its place with no unnecessary elaboration.

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

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

Given the tool's moderate complexity, the description covers the algorithm, termination conditions, and cost. Output schema exists, so return values are not required in the description. The only minor gap is not specifying what happens after attempts are exhausted, but the description implies a stop condition.

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%, providing baseline 3. The description adds context for threshold and max_attempts by explaining the escalation and stopping criteria, and implies json_schema drives quality scoring. This adds meaningful semantics beyond the schema.

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

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

The description clearly states the tool re-runs an actor with progressively stronger anti-blocking settings until a quality threshold is met, distinguishing it from related tools like run_actor or scrape_url. The specific verb 're-run' and resource 'actor' make the purpose unambiguous.

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

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

The title and description clearly imply use for low-quality runs that need retrying with escalation, but it does not explicitly state when not to use or mention alternatives. The context is clear enough for an agent to infer appropriate usage.

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

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

Annotations indicate readOnlyHint=false and openWorldHint=true, so the description does not repeat those. It adds meaningful behaviors beyond annotations: 'Costs Apify credits' reveals a side effect not captured in annotations, and 'allowlisted' imposes a constraint on which actors can be run. No contradiction with annotations.

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

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

The description is four concise sentences, each conveying essential information: action, return handles, cost, and alternative. It is front-loaded with the primary verb and avoids any redundancies or extraneous details. This is a model of efficient structure.

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?

The tool is a mutating, external operation with 5 parameters and an output schema. The description covers purpose, return handles, costs, and a usage alternative. Combined with schema descriptions for wait_secs and input, it gives sufficient context for selection and invocation. Gaps remain for memory_mb and timeout_secs semantics, but these are optional and have schema-specified ranges, making them less critical.

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 60%; input, actor_id, and wait_secs have descriptions, but memory_mb and timeout_secs lack them. The tool description adds only minor parameter context (e.g., 'explicit input object' already in schema), and does not explain the purpose or effect of memory_mb or timeout_secs. It doesn't adequately compensate for the schema gaps.

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 the action: 'Start an allowlisted Apify actor with an explicit input object.' It identifies the specific verb (start), resource (Apify actor), and scope (with input object). It also distinguishes from siblings by noting it returns run_id and dataset_id handles for follow-up tools, and explicitly prefers scrape_url for simple page scrapes.

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 an explicit alternative: 'Prefer scrape_url for simple page scrapes.' This tells the agent when not to use this tool. It also implies when to use it: when a more complex custom actor run is needed. Mentions of get_run_status/fetch_dataset_items/validate_dataset indicate the workflow where this tool is the entry point, offering clear context on usage.

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

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

The description significantly enriches the sparse annotations. It discloses cost ('Costs Apify credits per run'), the multi-step behavior ('runs a crawler, waits, scores the result... automatically retries with stronger settings'), and quality criteria ('completeness, bot-wall detection'). This contextualizes the non-read-only and open-world hints beyond what annotations provide.

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

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

The description is two concise sentences: the first states the core function and mechanism, the second covers cost and the sibling alternative. Every clause adds value without redundancy or fluff, making it well-structured 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?

Despite the tool's moderate complexity (4 params, output schema, annotations), the description covers the purpose, workflow, retry logic, cost, and a key alternative. The output schema exists to define return values, so the description doesn't need to explain them. It is complete for an agent to select and invoke the tool appropriately.

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 explains all four parameters clearly. The description adds useful pipeline context (e.g., 'automatically retries with stronger settings' clarifies quality_retry) but does not individually elaborate on parameter syntax or defaults beyond schema, so the baseline of 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 clearly states the tool's specific functionality: 'Scrape a public web page into clean markdown in one call.' It distinguishes from sibling tools by explicitly naming run_actor as the alternative for 'arbitrary actors or fire-and-forget runs.' This is a specific verb+resource+result with clear differentiation.

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

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

The description provides explicit when-to-use guidance, noting it is for quality-gated scraping with automatic retries. It also gives an alternative: 'For arbitrary actors or fire-and-forget runs use run_actor instead.' While it doesn't address all siblings, the key distinction from the closest alternative is clear.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds meaningful behavioral context by explaining what quality metrics are computed and how the score should influence the decision to consume or retry, without contradicting the annotations.

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

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

Two sentences, front-loaded with the core purpose and followed by actionable advice. No filler or redundancy; every word contributes to clarity.

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

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

With an output schema available, the description does not need to explain return values. It covers the tool's purpose, key inputs (optional schema), and decision process, which is sufficient for an agent to select and invoke the tool appropriately in most contexts.

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 67%, with json_schema and sample_size described. The description adds value by clarifying that json_schema is optional and what role it plays in the score, but it does not explain dataset_id or sample_size beyond the schema. This is adequate but not exceptional.

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

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

The description uses a specific verb 'Score' with a clear resource ('a dataset') and lists concrete quality dimensions (schema pass rate, field completeness, duplicate rate, bot-wall detection). It distinguishes itself from siblings by tying directly to retry_low_quality_run, making its role unambiguous.

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

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

The description provides clear usage context: use it before trusting data, and use the resulting score to decide between consuming or retrying. It names a specific alternative (retry_low_quality_run), but does not explicitly state when not to use the tool versus other siblings like fetch_dataset_items.

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