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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the no-effect-on-terminal-states rule, which is exactly what makes the idempotent hint meaningful, plus the fact that updated run details come back. It omits auth/permission requirements and any rate-limit behavior.

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

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

Front-loaded with the core action and the state constraint, and every prose sentence earns its place. The 'USAGE EXAMPLES' block of raw user_input lines is mostly decorative and pads the definition slightly.

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

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

With an output schema present, return values need not be spelled out, and the description still notes that updated run details are returned. For a two-parameter mutation with full annotation coverage, only auth requirements are unaddressed, which is a minor gap.

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

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

Schema description coverage is 100%, so both parameters and the 30-second graceful-abort timeout are already documented in the schema. The description only gestures at 'gracefully' via an example, adding no syntax or semantic meaning beyond the schema. 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 (Abort) plus resource (Actor run) and a state qualifier ('currently starting or running'), which immediately distinguishes it from siblings like call-actor and get-actor-run. An agent can select it 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?

Explicit when-to-use ('stop a run that is taking too long or misconfigured') and an explicit no-op condition (terminal statuses such as SUCCEEDED, FAILED, ABORTED, TIMED-OUT). It does not name an alternative tool or describe prerequisites, so it falls 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?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true): it discloses the wait/poll model, that non-terminal runs return a nextStep with polling instructions, that dataset field metadata is returned when waitSecs > 0, and that results are fetched via get-dataset-items with the returned datasetId. It also clarifies an important boundary — MCP server Actors are not executed here.

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

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

Front-loaded with workflow and constraints, which is good, but it is noticeably redundant: the 'dedicated tools first' rule appears in the two-ways section, again under USAGE, and again in IMPORTANT. Trimming one of those passes would keep the same information at roughly half the length.

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 generic, open-world dispatcher with a nested input object and an output schema, everything an agent needs is present: prerequisites, the wait/poll contract, where results land, and when to prefer a dedicated tool. Nothing material is left to inference.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds real nuance by explaining what waitSecs buys you at each end of its range and by pointing at the actor name format and the need to derive 'input' from the Actor's own schema. It does not add meaning for callOptions beyond what the schema already says.

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 ('Call any Actor from the Apify Store') and immediately scopes it against the alternatives: dedicated Actor tools and call-actor-mcp-tool for MCP server Actors. An agent can distinguish this from every sibling without opening a schema.

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

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

Explicit routing rules: use dedicated tools when available, use this generic tool otherwise, run fetch-actor-details first to get the input schema, and use search-actors if the name is not in 'username/name' form. It also gives selection guidance for waitSecs (0 for long-running, default for fast actors).

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

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

Beyond the destructive/openWorld/non-idempotent annotations, the description discloses non-obvious side effects: connecting requires an Apify API token, can start a Server Actor run that persists until idle timeout, and a multi-tenant Server Actor charges per event. Failure behavior (nonexistent actor or tool) is not covered, which keeps it from a 5.

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

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

The core action is front-loaded in sentence one, with cost/persistence caveats in the middle and a compact example at the end. No sentence is pure filler, though the example JSON partially restates 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?

No output schema exists, and the description only says it returns the target tool's result while noting that behavior "depends on the Actor" — acceptable given the result shape is inherently delegated. The important hidden costs and resource-lifecycle facts are present.

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

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

Schema description coverage is 100%, so the schema already defines actor, tool, and arguments. The description's example call reinforces the "username/name" form and the {tool, arguments} pairing, but adds no semantics the schema lacks about the free-form arguments object.

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?

First sentence states a specific verb and resource (call one tool on an Actor's MCP server, return its result) and points at fetch-actor-mcp-tool-list as the discovery counterpart. It does not address the adjacent sibling call-actor, so an agent can't fully disambiguate between the two 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?

"Use when the user asks to call a tool on an Actor's MCP server" plus a worked user_input example gives implied context, but there is no when-not guidance and no explicit comparison to call-actor, which is the most plausible alternative for the same intent.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the description correctly spends its budget elsewhere: it discloses the default field set ("all fields except outputSchema and serverInterface"), the summary-vs-full README behavior, and that it does not connect to an MCP Server Actor. It does not mention auth requirements or any size/rate caveats beyond the per-field byte limit already 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?

Front-loaded with the identifier requirement and the anti-hallucination warning before the optional output tuning. Bulleted output modes and example questions are scannable, and no sentence is 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 2-parameter read tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: identifier format, the failure mode to avoid, fallback sibling, and how to control response size.

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 would be 3; the description earns above that by documenting the default output composition and giving concrete selective patterns (inputSchema only, description + readme, serverInterface true vs. "GET /search"). The readme summary/full nuance is restated from the schema but the default and usage patterns are genuinely new information.

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

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

Specific verb + resource ("Get detailed information about an Actor by its ID or full name") with the accepted identifier format spelled out. It also differentiates itself from siblings by noting it does not connect to an MCP Server Actor and that fetch-actor-mcp-tool-list handles MCP tool listing.

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 the precondition ("Requires the exact ID or full name — do not construct a plausible-looking name") and routes the agent to search-actors when it has only a description or partial name. Example queries at the end map user intents to this 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?

Discloses traits the annotations cannot express: no caching, re-querying the server each call, API-token connection, potential start of a Server Actor run held until idle timeout, and per-event billing for multi-tenant servers. This usefully explains why readOnlyHint is false for a 'list' operation. The main omission is that the returned list's shape or failure modes (e.g. what happens when the Actor exposes no MCP server) aren't hinted at beyond the field 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?

Front-loaded with the core purpose, then a distinct USAGE block and an example. Every sentence carries information — the caching, token, run-lifecycle, and billing notes all matter for correct invocation, and nothing is repeated.

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?

Output schema exists so return values need no explanation, and the description still summarizes the returned fields. Cost/lifecycle side effects and the sibling relationship are covered. Minor gap: no guidance on prerequisite connectivity or error cases, though this is largely implied by the token/run notes.

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 single 'actor' parameter is fully documented in the schema, so the description adds only the implicit framing that the parameter identifies an MCP server Actor. With the schema doing the heavy lifting, 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 ('List an Actor's MCP tools') and enumerates exactly what is returned (name, description, input schema, annotations, metadata). It also explicitly contrasts with the sibling call-actor-mcp-tool, which calls one of them by name, so an agent can pick between them without opening either schema.

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

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

Gives a concrete trigger ('when the user asks which MCP tools an Actor provides') plus the preparatory case ('before calling one of them'), and includes a usage example. Alternatives are addressed by naming call-actor-mcp-tool as the follow-up action.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is clear. The description adds that it fetches 'full content', which is consistent but does not disclose any additional behavioral traits (e.g., rate limits, auth). Since annotations carry the burden, a score of 3 is appropriate.

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 concise, with two main sentences plus a usage section and examples. It is well-structured and front-loaded, containing no unnecessary words. Every part earns 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?

Given the tool has a single parameter, an output schema (so return values are documented), and good annotations, the description is adequately complete. It explains when to use and provides examples. A slight improvement could be mentioning expected behavior for invalid URLs, but not required.

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

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

The input schema has one parameter 'url' with a description, and schema description coverage is 100%. The tool description does not add additional semantic meaning beyond what the schema already provides, meeting the baseline of 3.

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

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

The description clearly states the tool fetches the full content of an Apify or Crawlee documentation page by URL. The verb 'fetch' combined with the specific resource 'docs page' provides a clear purpose, and it distinguishes from sibling tool 'search-apify-docs' which searches rather than fetches.

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 explicitly says to use this after finding a relevant page with 'search-apify-docs', providing context for when to use. It also includes usage examples. However, it does not explicitly state when not to use the tool, which would be helpful.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds real behavioral context beyond them: the summary vs. nextStep semantics, and that waitSecs blocks for up to 45s (default 30) before returning the current state. This is substantive added value, though it doesn't cover error/failure modes.

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

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

Front-loaded with the core purpose, then segmented into Returns/USAGE/EXAMPLES blocks. Every line carries information, though the two usage examples are somewhat redundant with the USAGE prose, adding minor length.

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

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

With an output schema present and 100% parameter coverage, the description need only orient the agent, which it does fully: purpose, when to use, wait semantics, and concrete invocation examples. 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%, so the baseline is 3, but the description goes further by framing waitSecs as a blocking/wait mechanism with its cap and default, and by describing what runId's run produces. Slight above-baseline value over the schema text.

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

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

States a specific verb and resource ('Get detailed information about a specific Actor run') and enumerates the returned result fields (status, storages, stats, summary, nextStep). It does not explicitly distinguish itself from siblings like call-actor or abort-actor-run, so it falls just short of the 5 benchmark.

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 USAGE block names the condition ('check the status of a run started by any Actor-running tool') and explains when to pass waitSecs > 0 to block until terminal. It gives clear context but stops short of explicit exclusions or naming the sibling to use for other run operations.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing the default limit of 20, what clean=true does, and that results are the raw rows. Return-shape details are largely deferred to the existing output schema, which is appropriate.

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

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

Front-loaded with the core purpose and the anti-scope sentence, followed by short usage notes and examples. Slightly redundant in repeating the limit default and the clean flag across sections, but nothing wasteful enough to hurt.

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

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

For a read tool with full schema coverage and an output schema, the description supplies the purpose, trigger, and key defaults an agent needs. Pagination interaction (offset/limit) and flatten behavior are left to the schema, which is reasonable given the output schema exists.

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 eight parameters in depth. The description only restates the default limit and clean=true semantics, adding little beyond the structured fields; 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 ('Get items (rows) from a dataset') and immediately delimits scope by saying it returns rows themselves, not metadata, counts, or schema. An agent can distinguish the intent 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 a clear trigger ('When the user provides a datasetId and asks to retrieve results, output, data, or rows, call this tool directly') plus a usage section and two concrete examples. It lacks explicit when-not guidance relative to any alternative, but the sibling list contains no competing dataset-read 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered elsewhere. The description earns credit for adding behavioral context beyond that: the 'requires the exact key name' precondition and the note that the response preserves the original Content-Encoding, which most clients decompress automatically — a real return-value trait callers would otherwise trip over.

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 key facts — scope, exact-key requirement, encoding caveat — are front-loaded in three tight sentences. The subsequent USAGE and USAGE EXAMPLES blocks are somewhat redundant with the first paragraph, costing a little efficiency.

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?

A two-parameter read tool whose annotations, 100% schema coverage, and output schema already cover safety, inputs, and return shape. The description closes the remaining gap with the Content-Encoding behavior, which is exactly the non-obvious detail an agent needs.

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

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

Schema description coverage is 100%, including the keyValueStoreId resolution rules (name vs. username~name) and minLength constraints in the schema itself. The description only reinforces that the key must be exact, adding little semantics beyond what the schema already documents, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the value stored under a specific key in a key-value store') and preemptively scopes it against a listing tool: 'a single record, not a listing of all keys.' An agent can immediately tell this is a point lookup, not an enumeration.

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 says when to use it ('when you need to retrieve a specific record (JSON, text, or binary)') and includes two concrete usage examples showing the store identifier formats. However, it never states when NOT to use it or names an alternative/sibling for enumeration, so the guidance is implied rather than comparative.

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

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

Annotations cover the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds genuinely new behavioral context: a privacy constraint forbidding personal data, credentials, secrets, and verbatim private conversation content, plus the downstream effect that reports help other users. It does not describe what happens after submission or any acknowledgment, so not 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 short paragraphs, each earning its place: purpose first, then the trigger examples, then the data-handling instruction. No filler, and the most important constraint (privacy) is stated last but explicitly.

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

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

With an output schema present, return values need not be explained, and the annotations already carry the safety profile. The description covers purpose, trigger conditions, and the privacy caveat, leaving no material gap for an agent deciding whether and how to call this 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 the baseline is 3, and the description adds actionable framing beyond it: it directs the agent to put the context ('what you were doing') and the failure in the 'message' field. It says nothing extra about actorId, actorRunId, or relatedTools, so a 4 rather than 5.

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

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

The description states a specific verb+resource (report a problem with Apify's MCP tools or Actors) and names the recipient (the Apify team). This is unmistakably distinct from every sibling tool, which are operational (search-actors, call-actor, get-actor-run, etc.).

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 enumerates concrete trigger conditions — missing tools or Actors, errors, timeouts, confusing results, multi-attempt steps, and tasks the available tools could not complete — which is strong when-to-use guidance. It does not state when NOT to report or name any alternative action, so it falls short of 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 read-only, idempotent, non-destructive behavior, and the description adds meaningful context: it does not run tasks or retrieve output, searches only public Actors, excludes rental/restricted Actors, and returns summary cards with inline input fields.

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

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

The description is front-loaded and clearly sectioned, with usage, limitations, and return information separated. It is somewhat long and repeats the non-retrieval point more than once, but the structure keeps it usable.

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

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

Complete for a search tool with annotations and an output schema: it explains purpose, alternatives, search scope, limitations, and how to use the keywords parameter. An agent has enough information to select and invoke it correctly.

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

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

Schema coverage is 100%, so all four parameters are already documented. The description reinforces keyword strategy, empty-keyword default ordering, and platform-only queries, but it largely repeats the schema and does not add much about limit or offset.

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: search the Apify Store to find/discover scraping Actors. It explicitly distinguishes itself from data retrieval, scraping execution, and actor detail lookup, which cleanly separates it from siblings like call-actor and fetch-actor-details.

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 scenarios such as finding tools for a platform or use case, and explicitly says to prefer Store search first when a relevant Actor may already exist. It also names the alternative for a specific Actor name: look it up directly rather than searching.

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 that the search returns only a limited content snippet and that full content must be fetched separately, which is important behavioral information. It also notes that it will not search the Apify Store, a limitation not present in annotations. While annotations already cover read-only and idempotent nature, the description adds useful context about output and limitations.

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 moderately concise, using bullet points for docSource and separating guidance for fetching full content. It has some redundancy in repeating the docSource details but is overall well-structured and not excessively verbose.

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

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

The description provides sufficient context given the tool's simplicity, including output expectations (URL and content snippet) and a mention of the fetch-apify-docs tool for full content. It covers the main usage scenarios and does not leave major gaps in understanding.

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 comprehensive descriptions for all parameters, including the query, limit, offset, and docSource with enums. The tool description reiterates the docSource options but adds little additional semantic meaning beyond the schema. Since coverage is 100%, the parameter semantics are well-covered by the schema alone.

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

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

The description clearly states the tool's function: 'Search Apify and Crawlee documentation using full-text search.' It also distinguishes the scope from the Apify Store and provides a clear verb-object structure. This effectively communicates the tool's purpose and differentiates it from sibling tools like search-actors.

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 usage instructions, such as 'You must explicitly select which documentation source to search using the docSource parameter' and recommends using fetch-apify-docs for retrieving full content. It also advises against searching the Apify Store unless specifically asked, guiding when to use this tool versus alternatives.

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