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

Annotations declare only readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the description carries real weight and does: it discloses that this call returns only a job ID, that the agent must poll firecrawl_agent_status until completed/failed, and that a run typically takes one to three minutes. It adds cost semantics (maxCredits caps spend), thread continuation with inherited settings, and the full gated-provider/terms approval path including skippedProviders and approve/decline — none of which is inferable from 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?

Well front-loaded: purpose and the sibling routing come first, then the async/thread mechanics, then terms handling. The terms paragraph is dense and partially restates schema descriptions for exchange.approve and onTermsRequired, and the dashboard URL is verbose, but given a 9-parameter async tool with nested exchange objects most of the length 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?

An output schema exists, so return-value shape need not be explained, yet the description still supplies the critical lifecycle fact that the response is a job ID to be polled. Combined with cost limits, thread continuation, and the terms-approval resumption protocol, an agent has everything needed to call this correctly and to recover from a pendingApproval.

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?

Given 9 parameters at 67% schema coverage, the description compensates well: it explains prompt as the field description, schema as optional JSON output shape, urls as seeds, effort as reasoning budget, maxCredits as spend cap, strictConstrainToURLs as a hard constraint, and threadId as thread continuation with settings carry-over. It also walks through exchange.approve/decline and exchange.onTermsRequired behavior. Minor gap: the mode extract-vs-chat distinction and exchange.toolkits/maxCalls are only lightly touched.

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

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

The opening sentence gives a specific verb and resource ("Run web research") plus the exact conditions that select this tool: URLs unknown or answer spans several sites, returning JSON assembled across sources. It also names what this tool is not, contrasting it with firecrawl_scrape for one known URL and firecrawl_search for a plain lookup, so an agent can disambiguate among 27 siblings without opening a schema.

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

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

The description gives concrete use cases (research an entity plus fields, build lists/datasets, pages needing navigation) and explicitly routes competing cases to firecrawl_scrape and firecrawl_search. It also states the follow-up protocol (continue a thread via threadId) and the terms/approval workflow. It stops short of an explicit "do not use this when..." exclusion beyond the 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?

Annotations already establish that this is a safe read-only operation, and the description adds valuable behavioral context beyond them: `processing` responses are non-terminal, polling cadence is specified, and typical duration is disclosed. The fallback advice further helps an agent avoid indefinite polling.

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

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

The description is front-loaded with purpose, then immediately provides polling behavior and fallback guidance. Every sentence adds concrete operational value without repetition.

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

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

For a simple read-only polling tool with an output schema, annotations, and one parameter, the description covers the missing operational concerns: terminal vs non-terminal states, retry timing, expected duration, and fallback strategy. Nothing essential for correct invocation is missing.

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

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

The schema has only an undocumented `id` string, and the description compensates by clarifying that it is a `firecrawl_agent` job ID. It does not specify formatting or where the ID is obtained, but for a single required parameter the added meaning is substantial.

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

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

The description states a specific verb and resource: retrieving progress or final results for a `firecrawl_agent` job ID. It clearly distinguishes this status-checking tool from the initiating `firecrawl_agent` tool and from unrelated siblings by naming the job ID dependency.

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

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

It gives explicit polling guidance: check every 15–30 seconds until `completed` or `failed`, with expected runtimes. It also names fallback tools (`firecrawl_search` and `firecrawl_scrape`) for cases where the job cannot finish in time, which is strong when-to-use and alternative guidance.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description's 'only reads Firecrawl job state' largely restates them. It does add the useful fact that results become available incrementally with progress, but says nothing about polling cadence, terminal states, or behavior on an expired/invalid ID.

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 operation and followed by the scope boundary. 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?

An output schema exists, so return values needn't be explained, and the read-only, non-mutating nature is covered. The only real gap is polling/terminal-state guidance, which is minor for a status-read 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 0%, so the description must carry the id parameter, and it does clarify that it is an 'existing crawl ID' rather than a URL or job name. It adds no detail on where such an ID comes from or its expected format.

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 ('Retrieve') plus resource ('current status, progress, and available results') scoped to an existing crawl ID, which distinguishes it from the starting tool. It stops short of naming firecrawl_crawl explicitly, so sibling differentiation is implicit rather than stated.

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?

'for an existing crawl ID' implies this is a follow-up to starting a crawl and that a valid ID is a prerequisite. It never says when to prefer this over firecrawl_crawl or what to do if no crawl exists yet, leaving the workflow 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?

The annotations only cover the safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent), while the description adds the important traits the agent actually needs: the call 'polls it to a terminal state' (that is, it blocks until completion) and results 'can be large.' It also calls out safe-mode restrictions that silently disable certain parameters. Missing only auth/cost and whether the crawl is cancellable.

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 paragraphs with the core action and scope controls front-loaded and the cost warning before the return-value line. The closing sentence partially duplicates the opening ('return the final status and collected data' vs 'Returns the crawl ID, status, and page data'), which is the only real waste.

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

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

Given a very large nested schema and an existing output schema, the description still covers the agent-critical facts: that this is a long, blocking, multi-page operation whose output scales with scope. It leaves adjacency questions (when to use this versus scrape or check status) unanswered, which is the main gap for a tool this complex.

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?

With 17 parameters, nested scrapeOptions, and 0% schema description coverage, the description's group-by-group walkthrough (include/exclude paths, depth, limit, subdomain/external-link controls, sitemap, delay, scrape options) is the only semantic signal available and does help mapping intent to knobs. But it gives no meaning for values or defaults and never mentions prompt, webhookHeaders, maxConcurrency, ignoreQueryParameters, or deduplicateSimilarURLs, so roughly half the surface stays opaque.

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 and resource: 'Start a multi-page crawl at a website URL.' 'Multi-page' implicitly separates it from firecrawl_scrape, but no sibling (firecrawl_scrape, firecrawl_map, firecrawl_check_crawl_status) is named explicitly, so a reader must infer the boundary from the word 'multi-page'.

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 one actionable usage constraint, 'use conservative limits when full-site coverage is unnecessary,' and notes that webhooks and interactive actions are unavailable in safe mode. It never says when to prefer firecrawl_scrape for a single page, firecrawl_map for URL discovery, or firecrawl_check_crawl_status, so alternative routing remains implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: returned fields for each view, edge cases (null billing dates, newest endDate null, notice when splits/daily periods unavailable), and a non-obvious discrepancy where the byEndpoint split includes search usage that other figures omit.

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

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

The description is front-loaded with purpose and usage, then flows into return details and limitations. Every sentence carries useful information, but it is somewhat long for a tool with only four optional parameters; the density is justified by the edge cases described.

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 having an output schema, the description still explains return values and edge cases (null dates, notice semantics, split discrepancies), and it sets clear expectations about what cannot be attributed. Combined with rich annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds meaning beyond the schema: it explains that byEndpoint counts search usage extra (so rows can add up to more), and that bin selects monthly vs. daily periods. While not exhaustive for all interactions, it adds useful nuance over the schema 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?

The description states a specific verb and resource: 'Get the authenticated Firecrawl team's current credit balance or its credit usage over the last 90 days.' It clearly distinguishes between two sub-views (current vs. historical) and their purposes, making it trivial to separate from sibling tools like scrape or crawl.

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 guidance is given: 'Use the current view to answer how many credits remain or to check billing-period boundaries. Use the historical view to answer what credits were spent on and when.' It also states what the tool cannot do and points to alternatives (each tool's own result, dashboard Usage/Logs pages).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds index scope and ranked markdown results, but does not disclose index freshness, rate limits, authentication needs, or coverage limitations; with annotations covering the safety profile, this is adequate but not rich.

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 tightly written sentences: the first front-loads the search scope and use case, and the second states the result format. There is no filler or redundant content.

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

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

The tool has an output schema and rich annotations, and the description supplies the source scope and return shape. It omits alternative-tool routing but is otherwise complete for a straightforward search tool.

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

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

Schema description coverage is 100%, with descriptions for query, k, and the skills enum. The description adds no parameter-level meaning beyond what the schema already provides, 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, 'Search', and a precise resource: an index of public repositories, GitHub issues, merged pull requests, READMEs, and code documentation. It clearly scopes the tool to programming questions, though it does not name sibling alternatives such as firecrawl_search or firecrawl_research_search_papers to help differentiate.

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 use this for programming questions that need external documentation or upstream evidence, giving clear usage context. It does not state when not to use it or route the agent to generic web, academic, or government search 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?

Beyond the annotations (non-read-only, non-destructive, open-world), the description adds important behavior: the 20-minute Alexandria feedback window, rejection of late feedback, and possible 1-credit refunds subject to daily caps. It also advises omitting large page contents and raw outputs. It does not cover authentication or overwrite semantics, but the added behavioral detail is substantial.

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

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

The description is front-loaded with general usage and then structured into a separate Alexandria branch, and its length is mostly justified by the tool's complexity. The closing sentence about returned fields is redundant because an output schema exists, and some parameter guidance could be tightened.

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

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

For a complex 17-parameter feedback tool, the description gives strong coverage of the Alexandria workflow and timing constraints but is incomplete overall because many schema parameters are not explained in either the schema or the description. It also lacks guidance on choosing this tool over firecrawl_search_feedback.

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 0% across 17 parameters, so the description should compensate. It explains the key Alexandria fields (requestedWebsite, objective, rationale, providerFeedback, capabilityFeedback), capability issue codes, and requestedFunctionality requirements, but leaves many parameters (url, note, tags, issues, metadata, pageNumbers, missingContent, valuableSources, querySuggestions) undocumented.

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 and resource: 'Submit concise quality feedback for a completed search, scrape, parse, or map job.' It also covers the Alexandria variant. It does not explicitly distinguish itself from the sibling firecrawl_search_feedback, so it falls short of a 5.

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

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

The description states when to use the tool (for completed jobs) and gives explicit conditions for Alexandria sessions. It does not mention when to use a sibling such as firecrawl_search_feedback instead, nor does it state exclusions, so clear context is present but alternatives are absent.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is in operational behavior: 'Discovery is free', 'Discovery does not execute providers', and that contracts must be run through firecrawl_scrape. Those are genuinely useful non-obvious facts. It doesn't spell out pagination semantics or result-size limits beyond a passing 'nextTool' mention, keeping it at a 4.

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

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

Purpose is front-loaded and the prose is dense with actionable content. There is mild redundancy around firecrawl_search (mentioned as both the preferred default and the alternative for web results), and the middle 'Alexandria covers...' enumeration is long, but every sentence largely 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?

For an 11-parameter discovery tool with an output schema, the description covers purpose, routing, the discovery-vs-execution distinction, free-cost note, and the nextTool handoff. An agent has everything needed to call it correctly and interpret the result without opening other tools.

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

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

Schema coverage is 73%, so much is already documented, but the description adds real meaning: 'use query for semantic discovery or urls to find providers', and the implicit level progression ('With no arguments, browse categories, then providers and tools'). limit, offset, and includeCosts are not elaborated in the description, leaving minor gaps for a schema that already names them.

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 precise verbs (browse providers/workflows, read a contract) on a specific resource ('Alexandria data providers'), and immediately operationalizes the jargon with a domain list (companies, people, jobs, finance, etc.). It also distinguishes itself from the sibling firecrawl_search, so an agent can tell the two apart without opening either schema.

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

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

Names the default alternative explicitly ('Prefer normal firecrawl_search for a data task') and gives three concrete when-to-use conditions: contract not returned in full, browse a category when search found nothing, before scraping the same fields across pages. It closes with an explicit exclusion ('Use firecrawl_search when you also need web results'). This is textbook 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?

Annotations cover only readOnly/openWorld/destructive, and the description adds substantial non-obvious behavior: filters keep only index-labeled pages so filtered searches can silently drop relevant results, court labels are most complete for federal courts, and results may include historical versions, bill text, agency guidance, and third-party reproductions. It also prescribes verification of issuer, jurisdiction, effective status, and version before citing.

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

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

Front-loaded with purpose and scope, then filters, then returns, then verification and alternatives. Dense but nearly every sentence carries decision-relevant information; the results-verification block is slightly repetitive with the no-results warning.

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?

Covers the full call lifecycle for a 7-parameter, open-world search tool: when to use, filter caveats, what comes back, how much to trust it, and where to go next. With annotations and an output schema already present, nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining that the optional filters narrow results and, critically, that filtering can exclude relevant pages. It does not add per-parameter syntax, but that detail is already fully carried by the schema.

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

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

States a specific verb and resource ('Search US federal, state, and local statutes, regulations, codes, court opinions, and other government publications') and scopes it to legal/regulatory primary-text questions, which cleanly separates it from firecrawl_search and firecrawl_scrape.

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

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

Gives explicit routing: use firecrawl_scrape for a known URL or more page context, and general search for non-US questions or missing coverage. It also states a pre-call behavior (clarify missing jurisdiction or ambiguous as-of date) and warns that no hits does not prove no applicable law exists.

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

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

Beyond the annotations it discloses real operational characteristics: an isolated Firecrawl-hosted browser with no end-user cookies, empty session state by default, optional team-scoped profile reuse, a bounded code timeout, and the warning that actions run live so form submission has effects on the target site. The side-effect warning sits alongside destructiveHint=false but does not contradict it, since it describes site interaction rather than data destruction.

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: capability first, then isolation and profile state, then side effects and return shape. Each sentence adds information, though the block is dense and could be split into scannable guidance bullets for the input contract.

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 high-complexity, open-world tool it covers the essentials: session model, state isolation, side-effect risk, and return payload, and an output schema already documents results. The remaining gap is that session lifecycle (how a scrapeId is reused or terminated, and the role of related session controls) is only hinted at.

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 0%, so the description carries the burden, and it does explain the mutually exclusive url/scrapeId and prompt/code pairs plus the Bash/Python/Node language choice and the purpose of scrapeOptions.profile. However, the large nested scrapeOptions object (actions, formats, proxy, screenshotOptions, jsonOptions, etc.) goes entirely unexplained, leaving most of the schema surface undocumented.

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 capability set with a clear verb and resource: 'Open or reuse a live browser session to navigate a page, click controls, fill and submit forms, or run browser code.' This sharply separates it from sibling read-only tools like firecrawl_scrape or firecrawl_crawl, and the either/or input contract (url or scrapeId; prompt or code) is stated up front.

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 clearly frames when the tool applies (interactive page actions and browser code execution) and gives the selection rule between the two input modes. It does not explicitly name alternatives such as firecrawl_scrape for static content or firecrawl_interact_stop for ending the session, so the agent must infer the boundary.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds that resources are released and a success confirmation is returned, which is consistent with (not contradictory to) the destructive flag, but it omits auth requirements and the behavior on an expired/unknown scrapeId.

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 short sentences, zero filler, with the action and its resource front-loaded before the return-value note. Nothing here is redundant padding.

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 teardown call with a declared output schema and full annotation coverage, the description supplies everything essential. Minor gaps: no error/unknown-session behavior and no note on whether subsequent interact calls on the same scrapeId require a restart.

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 0% for the single parameter, so the description must compensate. It does clarify the key semantic point — the scrapeId identifies the live session to terminate rather than a document to fetch — but gives no format, prefix, or validation detail.

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 ('Stop') plus specific resource ('live interact session') scoped to a scrapeId. The pairing with the sibling firecrawl_interact is strongly implied by the naming and the 'live session' framing, though the description never names the sibling 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?

Usage is only implied: an agent infers this is the teardown call after an interact session is no longer needed. There is no explicit 'call this when…' guidance, no note about what happens if the session is already closed, and no stated alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context: it returns matching URLs rather than page bodies, and authenticated responses may include an id for optional map feedback. It does not discuss rate limits or pagination, but it goes meaningfully beyond the annotations.

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

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

The description is front-loaded with the core operation, followed by usage guidance, parameter roles, and sibling alternatives. Every sentence adds distinct information and there is no redundant restatement of 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?

An output schema exists, so return values do not need full explanation. The description covers what is returned, when to use it, alternatives, and parameter categories. Minor gaps remain around enum behavior for sitemap and default limits, but the definition is sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining that search narrows the URL list and that sitemap, subdomain, query-parameter, and result-limit options control coverage, effectively mapping the six parameters to their roles. It stops short of explaining the sitemap enum values and limit defaults.

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

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

The description states a specific verb and resource: enumerate URLs indexed under one website through Firecrawl without fetching page content. It also distinguishes this from sibling tools by explaining that firecrawl_scrape retrieves one page and firecrawl_crawl collects content across multiple pages.

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

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

It gives explicit conditions for use: URL inventory requests, locating several relevant pages, or when the desired page URL is unknown. It also names the alternatives and when to choose them, making the routing decision unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false), so the credit here comes from added context: the enumeration of page statuses, the goal-judging 'meaningful-change' decision, format variation by tracking mode (text diff vs. field paths with snapshot), and pagination via a `next` URL. That is meaningful behavioral disclosure beyond what annotations and the output schema alone convey.

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, each doing distinct work: retrieval scope, result semantics, then output format and pagination. The core action is front-loaded and there is no padding.

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?

Since an output schema exists, the description is not obliged to explain return values, yet it does so well. The gap is the required identifier pair (id and checkId) plus skip/limit pagination controls, which are undefined in both the schema and the description — an agent could easily mis-populate them.

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 0% across five parameters, so the description carries the full burden. It explains the enum values for `pageStatus` and hints at filtering semantics, but says nothing about `id` vs. `checkId` (the two required identifiers) or about `skip`/`limit`, leaving the majority of parameters undocumented anywhere.

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 combination: 'Retrieve one monitor check and its page-level results'. The singular 'one monitor check' distinguishes it from the sibling firecrawl_monitor_checks listing tool, though that contrast is implied rather than named.

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?

Usage is implied by the optional page-status filter and pagination language, giving an agent enough to know this is the single-check detail read. However, it never explicitly says when to use this versus firecrawl_monitor_checks or firecrawl_monitor_get, nor does it state prerequisites such as needing an existing check.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are "one page of check summaries and pagination metadata," which is genuinely useful for a paged list, but it does not explain how paging is advanced or what the summaries contain.

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 short sentences, front-loaded with what is listed and followed immediately by what is returned. No filler or redundant restatement of 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?

An output schema exists, so return-shape detail is rightly omitted. But for a four-parameter paged list with 0% schema coverage, the missing treatment of `offset` and the required monitor `id` leaves the definition thin for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the load, yet it only gestures at two of four parameters (status, limit). The required `id` and the `offset` paging parameter are never mentioned, leaving the paging contract ambiguous.

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 ("List historical checks for a monitor") with scope qualifiers (status filter, result limit). It does not, however, name the near-identical sibling firecrawl_monitor_check (singular) or firecrawl_monitor_list, so an agent must infer the boundary itself.

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?

"Optionally filtered by status and bounded by a result limit" implies the conditions under which filters are used, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as firecrawl_monitor_check for a single check.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so safety is partly covered. The description adds real behavioral context beyond them: the monitor schedules future network checks, can emit email/webhook notifications and diffs, retains prior results for comparison, and returns the created monitor. It does not disclose credit cost, quota limits, or how to remove the schedule afterward.

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 purpose, then form selection, then precedence and side effects. Efficient overall, though the `body` enumeration ('targets, schedule, change-tracking formats, judging, retention, webhook, and notifications') is a compressed noun list that gives little actionable detail for its 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?

An output schema exists, so the single line 'Returns the created monitor' is sufficient for return values. But for a 15-parameter creation tool with a raw free-form `body` object and 0% schema description coverage, leaving most simple-form properties undocumented is a meaningful gap for an agent attempting to construct a valid 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?

With 0% schema description coverage the description must carry the load, and it does explain the most consequential parameters and their interaction (`goal` required in simple form, `page`/`pages` vs `queries` precedence) plus the broad remit of the free-form `body` object. However, roughly half the declared properties — `name`, `email`, `timezone`, `maxResults`, `includeDiffs`, `scheduleText`, `searchWindow`, `includeDomains`/`excludeDomains` — are never mentioned, and the `body` contents are listed abstractly ('judging', 'retention') rather than mapped to fields.

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

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

The opening sentence names the verb (Create) and the exact resource (a recurring scrape/crawl/search monitor) and states the defining behavior that separates it from siblings: each check is compared against its retained predecessor. An agent can distinguish it from firecrawl_monitor_run, firecrawl_monitor_check, or firecrawl_monitor_update 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?

It clearly splits usage into two modes (simple form vs. advanced `body` form) and states an explicit precedence rule: if `queries` has non-empty values alongside `page`/`pages`, the search target wins and page targets are ignored. It also states that a `goal` is required in the simple form. It stops short of saying when to prefer this tool over one-off firecrawl_search/firecrawl_crawl or what preconditions (auth, credits) apply.

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 destructiveHint=true and idempotentHint=true, but the description adds useful specifics: deletion is permanent, cannot be undone, and stops future scheduling. It also notes that deletion status is returned, though the output schema already covers return values.

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-loads the permanent deletion action, and every clause adds relevant information. There is no unnecessary repetition or 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 simple one-parameter destructive tool with rich annotations and an output schema, the description covers the key behavioral facts: permanence, schedule stopping, and irreversibility. The main remaining gap is that it does not explain where to obtain the monitor ID, but overall it 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?

There is one required parameter, id, with 0% schema description coverage. The description only says 'by ID', which adds no format, source, or validation detail beyond the parameter name and schema type.

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

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

The description states a specific verb and resource: permanently delete a Firecrawl monitor by ID. It also clarifies the effect of stopping the future schedule, which makes the tool's purpose unambiguous against sibling monitor tools like get, list, run, and update.

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 implies usage by saying this permanently deletes and stops scheduling, but it does not explicitly state when to choose deletion versus alternatives such as update or stopping a schedule. The irreversible nature is clear, but no alternative-routing guidance is provided.

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, and openWorldHint=false, so the safety profile is fully covered. The description adds that the response includes configuration and current state and reaffirms no side effects, which is mild added context but not beyond what annotations imply.

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 short sentences, front-loaded with the verb and resource, with no redundant or filler content. The clarifying negative clause is worth its 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?

An output schema exists, so return details needn't be explained, and annotations cover the safety profile. For a one-parameter lookup tool the description is essentially sufficient, with only the lack of sibling routing as a remaining gap.

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

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

Schema description coverage is 0%, so the 'id' parameter is undocumented structurally; the description only says 'by ID', which adds little beyond the property name and type. The single trivial parameter keeps the gap small.

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

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

States a specific verb ('Retrieve'), resource ('monitor'), and scope ('one ... by ID'), plus what is returned (configuration and current state). It implicitly separates itself from monitor_update/monitor_run via the negative clause, though it never names a sibling.

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 clause 'does not run or modify the monitor' signals a read-only fetch rather than monitor_run or monitor_update, which is useful exclusionary guidance. However, it doesn't state when to use this versus firecrawl_monitor_list or firecrawl_monitor_checks, leaving selection partly 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds account scoping and that results are a single page with pagination metadata, but omits ordering, default limit, and total-count semantics.

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 short sentences, front-loaded with the core operation and followed by return-shape context. No filler, though the second sentence partially duplicates what the output schema already conveys.

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?

An output schema exists, so return values needn't be spelled out, and the description correctly signals paging. What's missing is pagination mechanics (defaults, max limit, how to detect more pages) — important for a tool whose only parameters are pagination controls.

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 0%, so the description must carry the load for limit and offset. It only gestures at 'optional pagination controls' without defining default limit, maximum page size, or offset behavior, leaving the agent to guess.

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 monitors for the authenticated account') and scopes it to the caller's account. An agent can distinguish it from firecrawl_monitor_get (single monitor) by inference, but the description never names that sibling 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?

Implies usage by saying it returns 'one page' with optional pagination controls, which hints at iteration. However, it never says when to prefer this over firecrawl_monitor_get or firecrawl_monitor_checks, and gives no guidance on default page size or how to paginate further.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the initial bar is low. The description adds two valuable facts beyond the annotations: the call 'starts network work for the monitor's configured targets' (explaining why it is not read-only and why it is not idempotent) and that it 'returns the queued check', making the asynchronous queue semantics explicit. It does not mention credit cost, which is the main remaining gap.

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: the action statement is front-loaded and the network/return behavior follows. Every sentence adds distinct information, with no filler.

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

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

With an output schema present, the description does not need to enumerate return values, and it correctly summarizes the key behavior (returns the queued check, triggers network work). For a mutation-style, open-world, non-idempotent tool, the one remaining gap is the lack of parameter clarification and any credit/cost note.

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

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

There is one required parameter with 0% schema description coverage, so the description must carry the meaning. It implies the parameter identifies a monitor ('for a monitor'), but never states 'the monitor ID', leaving open whether the id refers to a monitor, a check, or a target. Since there is only one obvious parameter, the inference is easy, but the description forgoes valuable disambiguation.

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 gives a specific verb and resource: 'Queue an immediate check for a monitor', and adds the scope qualifier 'outside its normal schedule', which distinguishes it from the scheduled-monitor siblings (firecrawl_monitor_checks / firecrawl_monitor_check). It does not name a sibling explicitly, so it falls short of a 5.

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

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

'Queue an immediate check ... outside its normal schedule' tells the agent clearly when to reach for this tool: when an out-of-band run is wanted rather than waiting for the schedule. There are no explicit exclusions or named alternatives (e.g., 'do not use to read past results — use firecrawl_monitor_checks'), which keeps it at 4.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine context beyond them: the effect is scoped forward ("these changes affect future scheduled checks") and the call returns the updated monitor. It still does not say what a destructive patch can overwrite or remove, e.g. whether omitted fields are left intact or whether the targets array is replaced wholesale.

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 plus a one-line return note, with the core action front-loaded and the field enumeration kept compact. No filler or repetition of 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?

An output schema exists, so omitting return-value detail is appropriate, and the annotation set covers safety. Given the nested, wholly undocumented body object, the description is close to complete but leaves the partial-vs-replace question and sibling routing unaddressed.

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 0% and the body is a free-form object with additionalProperties=true, so the schema alone tells an agent nothing. The description partially compensates by naming the categories of fields the body accepts, but gives no formats, no indication of which keys are required or partial-update semantics, and no explanation of the id beyond "by ID".

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?

"Patch an existing monitor by ID" gives a specific verb and resource, and enumerates the mutable surface (name, status, schedule, targets, goal, judging, webhook, notifications, retention). It is clearly distinguishable from monitor_create/monitor_delete/monitor_get, though it never names those siblings 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?

Usage is implied by "patch an existing monitor" and by the note that changes affect future scheduled checks, which hints this is a configuration change rather than an immediate run. There is no explicit routing guidance such as "use firecrawl_monitor_run for an immediate check" or "call firecrawl_monitor_get first to read current settings."

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

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

Beyond the annotations (which only declare read-only, non-destructive, closed-world), it discloses the hosted two-phase protocol, that phase one returns upload instructions rather than content, that `zeroDataRetention` requires an eligible authenticated account and must be omitted for keyless use, PII redaction behavior, and the optional `data.metadata.scrapeId` for feedback. That is substantial context an agent could not infer from annotations alone.

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 output modes, then organized into input types, local-vs-hosted protocol, and option notes. Dense but each sentence carries operational content; the hosted-flow paragraph is the longest and could be tightened, but nothing 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?

Return values are covered by the output schema and the description usefully notes phase-one vs final responses, so that burden is met. However, for a 17-parameter tool with nested objects, the vast majority of options are unexplained, and the `uploadRef` instruction is not representable in the published schema — a gap an agent will hit on the hosted path.

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?

With 17 parameters and only 18% schema description coverage, the description must carry most of the semantic load, yet it explains only `filePath`, `pdfOptions.maxPages`, `redactPII`, and `zeroDataRetention`. Formats, `parsers`, `jsonOptions`/`queryOptions`, `includeTags`/`excludeTags`, `onlyMainContent`, `storeInCache`, `proxy`, `maxAge`, and `contentType` are left undefined. Worse, the description instructs sending `uploadRef`, which does not exist in the schema (which is `additionalProperties: false` and requires `filePath`), creating ambiguity about how the second hosted call is actually formed.

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 ('Parse one supported document') plus the concrete output modes (markdown, HTML, links, summary, targeted answers, schema JSON) and the accepted input families. It also explicitly separates itself from `firecrawl_scrape` for remote web URLs, 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/when-not: local MCP reads `filePath` from the server filesystem, hosted MCP requires two calls (filePath → upload → uploadRef), never both fields together, and remote URLs belong to `firecrawl_scrape`. This is a genuine decision procedure, not implied 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 already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the payload is canonical metadata returned as markdown, which is useful, but says nothing about behavior for unknown/unresolvable IDs or any upstream rate limits.

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 action and scope, then the return shape. No filler or redundant phrasing.

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 read-only tool with an output schema, the description covers the essentials; return fields needn't be detailed. Minor gap: no note on what happens when the ID cannot be resolved or whether prefixed forms are mandatory.

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 single parameter already lists concrete example identifiers with prefixes. The description's 'one paper ID, such as an arXiv, PMC, PMID, or DOI identifier' restates that without adding format or canonicalization rules, 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 gives a specific verb and resource: 'Retrieve canonical metadata for one paper ID', and enumerates accepted identifier families (arXiv, PMC, PMID, DOI). The implied contrast with firecrawl_research_read_paper (metadata vs. full text) is inferable but not spelled out by name.

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?

Usage is only implied: 'for one paper ID' suggests calling it when an identifier is already known. There is no explicit when-not, no statement that firecrawl_research_search_papers should be used first to obtain an ID, and no mention of firecrawl_research_read_paper as the alternative for full content.

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 and non-destructive, and the description goes beyond them by disclosing the indexing precondition and the failure mode ('a notice when full text is unavailable'). It does not cover rate limits or what an empty/low-relevance result looks like, but the fallback disclosure is the substantive addition an agent needs.

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 short sentences, front-loaded with the core action and scope. The second sentence slightly overlaps the first by restating the return of matching passages, but there is no filler.

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

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

An output schema exists, so return values need not be spelled out. However, for a retrieval tool gated on an 'indexed papers' precondition, the description never tells the agent how to establish index status or what to do otherwise — a meaningful gap given the research_* sibling 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 coverage is 67% with well-documented paperId (formats) and k (range, default 4); only `question` lacks a schema description. The description's 'relevant to a specific question' and 'k controls the number of passages' largely restate the schema rather than adding format or quality guidance for the question phrasing.

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: retrieve in-body passages from one paper, targeted at a question. That distinguishes it from the metadata-oriented siblings (research_inspect_paper, research_search_papers), though it never names those siblings explicitly, leaving the agent to infer the boundary from tool names.

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?

Adds one real usage condition — full text is available only for indexed papers — but does not say how to check whether a paper is indexed, nor when to prefer inspect_paper or search_papers instead. Usage is implied by the name and sentence, not routed.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results are ranked and that an 'evaluated pool size' is reported, which hints at cost/scope, but it says nothing about latency, rate limits, or what happens with a weak seed set. With annotations in place, a 3 is fair.

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 dense sentences, front-loaded with the core action, then mode semantics, then the return shape. No filler or repetition of 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?

An output schema exists, so return values needn't be spelled out, and the description still summarizes the return shape. The only gap is the unexplained 'k' bound, which is minor for a read-only retrieval tool with a documented schema and annotations.

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 20%, so the description carries real weight here and mostly delivers: it explains seed_ids ordering semantics (first is primary, later are anchors), the mode enum values and default, and that intent drives ranking. It leaves 'k' (result count, max 500) unexplained, while 'rerank' is already documented in the schema.

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

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

Names a specific verb and resource ('Find citation-graph candidates') and scopes it to 'one to ten seed_ids'. The citation-graph framing clearly separates it from the sibling search/read/inspect paper tools, so an agent can pick 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?

Gives explicit when-to-use guidance for each mode: 'similar' (co-citation/bibliographic coupling), 'citers' for papers citing a seed, 'references' for papers cited by a seed, plus the default. It does not say when to prefer this over firecrawl_research_search_papers, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the description is not obligated to restate it. It adds real behavioral context beyond that: the indexed corpus's domain coverage, the fact that results are relevance-ranked, and the non-obvious ranking insight that rephrasing a question changes which papers surface. The final sentence mostly restates the output schema, which is the only wasted signal.

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 corpus scope, then filtering, then returns — a sensible order with no filler. The only redundancy is the closing sentence about return fields, which an output schema already provides, though it is brief enough not to be costly.

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 7 fully described parameters, an output schema and safety annotations, the description supplies the missing piece an agent needs — what corpus is being searched and how results are ranked. Minor gaps remain: no mention of result caps or pagination behavior across calls, and no explicit pointer to the companion research tools for reading or expanding a found paper.

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 every parameter (including k's default of 40, the from/to date format, and sort's semantics) is already fully documented in the schema. The description only summarizes that author, category, date and sort options 'constrain or reorder results', adding no syntax, format or default details beyond the structured fields. Baseline 3 applies where the schema carries the load.

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 ('Search paper metadata and abstracts') and immediately enumerates the corpus (PubMed, bioRxiv, medRxiv, arXiv, other scientific sources), which implicitly separates it from the generalist siblings firecrawl_search, firecrawl_developer_search and firecrawl_gov_search. It also states the result shape (ranked papers with canonical IDs, titles, authors, abstracts). It stops short of naming any sibling explicitly, so an agent must infer the routing.

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?

There is one genuinely useful usage cue — 'Several distinct framings of the same question surface different papers than a single query does' advises on query strategy — plus a note that filters 'constrain or reorder results'. But there is no explicit statement of when to choose this over firecrawl_search or when to follow up with firecrawl_research_read_paper / firecrawl_research_related_papers, so routing is left 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?

Beyond the annotations, it discloses non-obvious behavior: content may be recently indexed rather than live (with `maxAge: 0` as the escape hatch), success does not prove currency, interactive browser actions can mutate the live page, and alexandria calls can partially fail per-capability even when the outer response succeeds. It also flags the terms-acceptance flow and the `metadata.scrapeId` feedback hook. Nothing here contradicts readOnlyHint=false, openWorldHint=true, destructiveHint=false.

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 routing and format information is front-loaded and wastes nothing, but the paragraph block grows to five paragraphs and the terms-requirement sentence is duplicated almost verbatim from the `alexandria` schema description. The section on provider discovery across `firecrawl_search`/`firecrawl_find_tools` sits awkwardly between behavioral caveats and mode switching.

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?

An output schema exists, so return values need not be explained, and the dual url/alexandria mode, staleness model, and terms flow are all covered. What is missing is scale-appropriate: for a 28-parameter tool at 18% schema coverage, most optional knobs still have no explanation anywhere, which is the main gap for an agent deciding how to configure a 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 only 18% across 28 parameters, so the description carries most of the burden and mostly does not. It explains `maxAge`, sketches `formats`, gestures at `actions`, and covers `alexandria`/`requestId`/`timeout`, but leaves `proxy`, `profile`, `location`, `lockdown`, `redactPII`, `storeInCache`, `onlyMainContent`, `includeTags`/`excludeTags`, `zeroDataRetention`, `waitFor`, `mobile`, `parsers`, and the `jsonOptions`/`queryOptions`/`screenshotOptions` sub-objects undocumented in either place.

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

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

The opening sentence names a specific verb and resource ('Scrape one URL and return its content') and enumerates the concrete output shapes (markdown default, HTML, links, screenshots, branding, targeted answer, schema-matched JSON). It then distinguishes itself from three siblings by name and condition, so an agent can route without opening any schema.

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

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

It gives explicit selection criteria: use it when the request identifies a page ('the user gives a URL or names a page or PDF and wants it read or summarized, or wants prices, specs, contact details or a table from it'), and names `firecrawl_search`, `firecrawl_map` and `firecrawl_crawl` with the situations that select them. The alexandria paragraph adds a second routing condition (catalogued provider capability instead of a page fetch).

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