Firecrawl by Nova (CIVAI)

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

With no annotations, the description carries the full burden and does: it discloses that the call returns only a job ID, that results must be polled via firecrawl_agent_status for one to three minutes, that credits are spent (with a default 2500 cap via maxCredits), and that thread state carries over. It also covers the Alexandria provider gating path, pendingApproval flow, and the explicit warning not to infer terms acceptance.

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?

Five tight paragraphs with purpose first, then usage, then async behavior, thread, and terms handling — a logical order for a complex tool. The terms/provider paragraph is long and partly duplicates the exchange schema descriptions, so a little could be trimmed.

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?

Ten parameters, nested exchange object, no output schema, no annotations — yet the description supplies the missing pieces: what the immediate return is (a job ID), how to retrieve the result, expected latency, cost controls, and the multi-turn approval protocol. Nothing an agent needs to invoke and follow through correctly is absent.

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?

Most parameters get meaning beyond the schema: prompt as field description plus optional schema and seed urls, effort as reasoning budget, maxCredits as spend cap, strictConstrainToURLs as URL confinement, threadId as continuation with inherited mode/urls/schema, and the approve/decline exchange flow. Gaps remain for mode, conversationId, maxCalls and toolkits, which rely on the schema's own 70% coverage.

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

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

Opens with a specific verb and output shape: "Run web research that returns structured data when the URLs are not known or the answer spans several sites." It explicitly distinguishes itself from firecrawl_scrape (single known URL) and firecrawl_search (plain lookup), so an agent can route correctly without opening any schema.

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

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

Gives both when-to-use (research an entity plus fields, build lists/datasets, pages needing navigation or interaction) and when-not-to-use with named alternatives for each case. Also states follow-up continuation semantics via threadId, which is a usage condition in itself.

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

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

No annotations exist, so the description carries the full load, and it does disclose the key behavioral traits: polling semantics, the non-terminal `processing` state whose payload lacks the final result, and realistic run durations. It does not describe authentication, rate limits, or the shape of the result data beyond a one-line summary, leaving some burden on the caller.

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, then polling guidance, then fallback advice — a sensible priority order. The closing sentence about return values is mildly redundant with the opening sentence but earns some place given there is no output schema.

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

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

With no annotations and no output schema, the description supplies the polling loop contract, timing expectations, terminal states, and a fallback path, which is what an agent needs to drive this tool correctly. The one real gap is that `id`'s expected format/source is only hinted at, and the result payload is described only generically.

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

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

Schema coverage is 50%: `conversationId` is fully documented in the schema, while `id` has no schema description at all. The description partially compensates by identifying `id` as a `firecrawl_agent` job ID, telling the agent where to obtain it, but adds no format or validity details. Minimum-viable for a two-parameter tool with a coverage gap.

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 progress or final results") tied to a `firecrawl_agent` job ID, which immediately distinguishes it from the job-creating sibling. An agent can tell this is the polling counterpart to firecrawl_agent 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?

Explicitly names the terminal vs non-terminal conditions (`processing` vs `completed`/`failed`), gives a polling cadence (15–30 seconds), sets latency expectations (one to three minutes, longer for complex jobs), and names fallback alternatives (`firecrawl_search` and `firecrawl_scrape`) when time runs out. This is about as complete as usage guidance gets.

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

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

No annotations are provided, so the description carries the whole burden; it does disclose that the operation is read-only and non-mutating, which is the key safety fact. It omits other relevant traits: whether results are partial until the crawl completes, whether repeated polling is expected, and any cost or rate-limit considerations.

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 capability and followed by the scope constraint. No filler and nothing redundant with 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?

With no output schema and no annotations, the description should do more: it names 'status, progress, and available results' but never indicates what the status values are, whether results appear incrementally as the crawl runs, or how a caller should behave while status is still in progress. Adequate for identifying the tool, thin for actually using it in a polling loop.

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 only 50% – the required `id` parameter has no schema description, but the prose supplies 'existing crawl ID', which adequately conveys its meaning. The `conversationId` parameter, which has its own schema description, is not addressed in the prose at all, so the description compensates only partially.

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 the current status, progress, and available results for an existing crawl ID') and immediately contrasts the scope with crawl-starting behavior ('does not start or modify the crawl'). An agent can distinguish this from firecrawl_crawl 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?

'for an existing crawl ID' makes clear the precondition that a crawl must already exist, and the negative clause rules out using it to launch work. However, it never explicitly says to call firecrawl_crawl first, nor whether/how often to poll for status updates, so guidance stops short of full when/when-not routing.

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

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

With no annotations, the description does real work: it discloses that this call blocks until a terminal state, that results can be large, and that webhooks/interactive scrape actions are unavailable in safe mode. It omits cost/credit implications, timeout behavior, and permission requirements, which matter for a long-running crawl.

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

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

Three short sentences, front-loaded with the core action before the scoping options and the warning. Little waste, though the middle sentence is a dense enumeration that borders on a parameter dump.

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 16 parameters, nested scrapeOptions, no annotations, and no output schema, the description covers the essentials: what it does, that it blocks to terminal state, key scope controls, a size warning, and the shape of the return value (crawl ID, status, page data). The gaps are mostly detail on individual advanced parameters rather than anything that would cause a wrong 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 coverage is only 6% across 16 parameters, so the description carries real weight. It groups several controls into plain language (include/exclude paths, depth, page limit, subdomain/external links, sitemap handling, delay, scrape options), which helps orientation. However, many parameters (prompt, maxConcurrency, ignoreQueryParameters, deduplicateSimilarURLs, and most nested scrapeOptions fields) remain unexplained.

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: start a multi-page crawl at a URL, poll it to a terminal state, and return status plus collected data. 'Multi-page crawl' implicitly distinguishes it from firecrawl_scrape's single-page fetch, but no sibling tool is named explicitly.

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

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

It offers one usage cue ('use conservative limits when full-site coverage is unnecessary') and one environment constraint (no webhooks or interactive actions in safe mode). It never names alternatives like firecrawl_scrape, firecrawl_map, or firecrawl_check_crawl_status, so an agent must infer when a crawl beats a scrape or map.

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

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

With no annotations, the description carries the full burden and does so: it discloses returned fields per view, the edge case that extra purchased/granted credits make `remainingCredits` exceed `planCredits`, that billing-period dates and the newest `endDate` may be null, that the endpoint split double-counts search usage, and that a `notice` means requested splits/daily periods are unavailable. These are exactly the non-obvious behaviors an agent needs before trusting the numbers.

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

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

Purpose and the two-view decision rule are front-loaded, and each subsequent paragraph maps to a distinct concern (current view, historical view, limitations). It is dense but long for a 4-parameter tool; the detailed field-level return narration is justified only because no output schema exists, though some enumeration of field names could be trimmed.

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

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

No output schema exists, so the description must explain returns — and it does, per view, including nullability, sort order, and the `notice` fallback. It also closes the biggest likely misinterpretation (attributing credits to individual jobs) by pointing to per-tool `creditsUsed` and the dashboard, leaving nothing an agent needs missing before calling it.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining what each split actually means semantically (byEndpoint splits by scrape/search/crawl/map/agent and includes search usage the unsplit and per-key figures omit; byApiKey splits per API key) and by documenting the default monthly binning vs UTC daily periods. The view-selection interactions are mostly restated from the schema rather than added, keeping this just below the top score.

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 authenticated Firecrawl team's current credit balance or its credit usage over the last 90 days') and immediately partitions the tool into two named views, so an agent knows exactly what it retrieves. It also scopes itself against adjacent surfaces (dashboard Usage/Logs pages, per-tool `creditsUsed`), which separates it from firecrawl_usage_dashboard and the per-call tools.

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 is given per view: '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 further names the alternatives for attribution ('Each tool's own result reports what that call used... the Usage and Logs pages of the Firecrawl dashboard list usage per job'), including a clear when-not ('cannot attribute credits to individual jobs, URLs, or MCP clients').

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

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

No annotations are present, so the description carries the burden. It discloses the indexed sources and the return shape (ID, source type, URL, title, matched passages in markdown), which is valuable. It does not state read-only semantics, rate limits, freshness, or pagination behavior beyond k, leaving meaningful gaps for a no-annotation tool.

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

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

Two tight sentences with zero waste; the source scope is front-loaded and the return shape follows naturally. Every sentence 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 a 3-parameter search tool with no output schema, the description covers both the searchable corpus and the return fields, which is what an agent needs to call it correctly. Minor gaps (pagination, freshness) remain but are not blocking.

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's mention of library/error-message/API phrasing echoes what the query parameter already documents, and the 'skills' enum parameter is not explained in the description.

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

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

Specifies a clear verb (Search) and a well-scoped resource: an index of public repos, GitHub issues, merged PRs, READMEs, and code documentation. This distinguishes it thematically from firecrawl_search (general web) and firecrawl_research_search_papers (papers), though it stops short of naming 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?

The phrase 'for programming questions that need external documentation or upstream evidence' gives useful when-to-use context. However, there is no explicit when-not guidance and no named alternative (e.g., firecrawl_search) to route between, 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?

With no annotations, the description carries the full burden and does well: it discloses the 20-minute submission deadline, that late feedback is rejected, that eligible feedback can refund 1 credit, and that refunds are capped daily per website and per team. It also names the return fields (submission status, feedback ID, accounting fields). It does not cover auth requirements or idempotency/retry behavior, so it falls just short of a 5.

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

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

Purpose and the general-shape instruction are front-loaded in the first sentence, followed by the Alexandria special case and then the timing/refund consequences — a sensible ordering. The middle sentence is long and packs several unrelated requirements together, but there is little true 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 an 18-parameter, nested-object tool with no annotations and no output schema, the description covers the two required parameters and both main flows clearly, and it does describe return fields in prose. It nonetheless leaves many optional-but-meaningful parameters (pageNumbers, missingContent, valuableSources, tags, note) unexplained, so an agent cannot confidently populate a rich submission.

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 6% across 18 parameters, so the description must compensate, and it explains endpoint, jobId, rating, issues, objective, rationale, requestedWebsite, providerFeedback and capabilityFeedback plus the issue code list. However, it says nothing about url, note, tags, pageNumbers, missingContent, valuableSources, querySuggestions or the metadata object, leaving nearly half the surface undocumented in both places.

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: 'Submit concise quality feedback for a completed search, scrape, parse, or map job,' and enumerates the eligible job types. It is clear what the tool does, but it never distinguishes itself from the closely-named sibling firecrawl_search_feedback, leaving the agent to guess which feedback tool applies to a search job.

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 selection criteria for the alternative 'alexandria' mode: set endpoint to `alexandria`, omit jobId, and supply requestedWebsite/objective/rationale/rating, plus a timing window ('within 20 minutes'). It also tells the caller what to omit ('omit large page contents and raw outputs'). It stops short of stating when to use this tool versus firecrawl_search_feedback, which is the one remaining ambiguity.

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

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

With no annotations, the description carries the full burden and discloses key traits: discovery is free, discovery does not execute providers, contracts describe inputs/outputs for execution through firecrawl_scrape, and nextTool signals further discovery or pagination. It stops short of describing result sizes, rate limits, or the pagination mechanics behind offset/limit.

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 every sentence carries routing or behavioral information. There is mild redundancy in restating the discovery/free and non-execution points separately, but nothing that materially wastes space.

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

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

For a 13-parameter discovery tool with no annotations and no output schema, the description covers the core workflow, the contract-to-scrape handoff, and the nextTool continuation signal. Pagination parameters and cost inclusion are left entirely to the schema, which leaves a small gap in the overall picture.

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 77%, so the baseline is 3; the description adds practical semantics by pairing query with semantic discovery, urls with finding providers for a website, and describing the no-argument browse flow (categories, then providers and tools). It does not add meaning for offset, limit, includeCosts, or level beyond what the schema already documents.

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 names a specific verb and resource set: browsing Alexandria providers/workflows and reading selected contracts, with a concrete domain list (companies, people, finance, public records, real estate, etc.). It explicitly contrasts itself with firecrawl_search and firecrawl_scrape, so an agent can distinguish it from siblings without opening schemas.

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 when-not ('Prefer normal firecrawl_search for a data task; it already returns matching providers') and three concrete when-to conditions (contract not returned in full, browse a category after empty search, before scraping the same fields across pages). It closes by routing to firecrawl_search when web results are also needed.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses that filters rely on index labels, can exclude relevant pages, and that no results does not prove no law exists. It also warns that results may include historical versions, bill text, agency guidance, and third-party reproductions, and instructs verification of issuer, jurisdiction, status, and version.

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 every section has a purpose: scope, guidance, filter caveats, return format, verification, and alternatives. It is slightly repetitive in warning twice that no results does not mean no law exists, which keeps it from being maximally concise.

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 seven-parameter search tool with no annotations and no output schema, the description covers the return shape (position, title, URL, snippet), the reliability caveats, the filtering limitations, and the follow-up tools. Nothing essential for correct invocation appears to be 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 schema already documents all seven parameters, including the enum and jurisdiction pattern. The description adds useful operational meaning by explaining that filters narrow by jurisdiction, court, court type, cited law or case, and site, and by warning that filtered searches can miss relevant pages.

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: searching US federal, state, and local statutes, regulations, codes, court opinions, and government publications. It distinguishes the tool from general web search by tying it to legal or regulatory questions needing primary text.

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 explicitly names when to use it versus alternatives: use general search for non-US questions or missing coverage, and use firecrawl_scrape for a known URL or additional page context. It also states a prerequisite behavior: clarify missing jurisdiction or ambiguous as-of date before identifying the governing rule.

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

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

With no annotations provided, the description carries the full disclosure burden and does substantial work: it warns that actions run against the live site and that form submission can create persistent external side effects, and it states a bounded timeout and what the return payload contains. It stops short of session lifecycle details (what 'reuse' means, whether sessions persist after return) and any authentication or 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?

Two sentences, both front-loaded: the capability statement comes first, the risk and return information second. No filler, no restatement of the tool name, and the side-effect warning is placed where an agent will read it before choosing arguments.

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 0-annotation, no-output-schema, 8-parameter tool with a deeply nested options object, the description covers the core mechanics and the return shape but leaves the entire scrapeOptions tree and session/conversation continuity unexplained. An agent can invoke it with a url plus prompt, but cannot confidently configure the options or chain sessions.

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 13%, so the description must compensate, and it does explain the two alternative entry points (url vs scrapeId) and the two execution modes (prompt vs code) plus language choices — none of which are documented in the schema. However, the large nested `scrapeOptions` object (proxy, formats, profile, jsonOptions, screenshotOptions, etc.) and `conversationId` receive no mention, leaving most of the parameter surface undocumented in prose.

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 names a specific verb set (open/reuse a session, navigate, click, fill, run code) against a specific resource (a live browser session), which is far more informative than the tool name alone. It does not name the sibling it supersedes — notably firecrawl_scrape for static fetching or firecrawl_interact_stop for ending a session — so differentiation is left to inference.

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 conditional input guidance ('provide either `url` or `scrapeId`, and either a natural-language `prompt` or executable `code`'), which is closer to parameter pairing rules than to when-to-use guidance. There is no statement of when this is preferable to firecrawl_scrape, nor any exclusion such as avoiding it for simple static extraction or destructive form submissions.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key behavioral fact (releases session resources) and the return shape (success confirmation), but omits whether the call is idempotent, what happens if the scrapeId is unknown or the session already ended, and whether an error is thrown.

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, the action and its effect front-loaded, with zero filler. Nothing could be removed without losing information.

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

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

For a two-parameter teardown tool with no output schema, the description covers what it does, what it releases, and that it returns a confirmation. The remaining gap is failure/idempotency behavior and the origin of scrapeId, which is a modest omission rather than a blocking one.

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

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

Schema coverage is 50%: conversationId is richly documented in the schema, but scrapeId has no schema description. The description only restates that scrapeId identifies the session, without saying where it comes from (a prior firecrawl_interact result) or that conversationId is optional here.

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 ("Stop the live interact session associated with a scrapeId") plus the side effect (releases resources). The term "interact session" implicitly ties it to the firecrawl_interact sibling and makes the teardown role obvious, though it 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 can infer this is the cleanup call after a live interact session. There is no explicit statement of when to call it (e.g. at end of session vs. on error), no exclusion, and no named alternative such as letting the session expire.

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

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

With no annotations, the description carries the burden and does well: it discloses that pages are not fetched, that the return value is URLs rather than bodies, and that authenticated responses may include an `id` for feedback. It stops short of disclosing cost/credit consumption, pagination of large maps, or error/permission behavior, which keeps it below 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?

Five tight sentences, front-loaded with the core action and scope, then triggers, then parameter effects, then return semantics, then sibling routing. No sentence is redundant.

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

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

No output schema and no annotations make the description the sole source of behavioral information, and it covers action, return shape, alternatives, and session-id context. Gaps remain around large-site pagination behavior and the precise semantics of the sitemap enum, which a 7-parameter tool would benefit from.

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 only 14%, so the description must compensate, and it substantially does: it explains what `search` does (narrows the URL list) and groups sitemap, subdomain, query-parameter, and result-limit options by their effect on coverage. It does not explain the sitemap enum values (include/skip/only) or default limits, so it is not fully compensatory.

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: 'Enumerate URLs indexed under one website... without fetching each page's content.' The negative clause immediately separates it from the content-retrieval siblings, so an agent knows this is an inventory operation, not a 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 three concrete trigger conditions (URL inventory request, locating several relevant pages, unknown target URL) and then explicitly routes alternatives: 'Retrieve one page with firecrawl_scrape; collect content across multiple pages with firecrawl_crawl.' When-to-use and when-not-to-use are both present.

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 goes far beyond the input schema by detailing the three specific output formats (Markdown diff, JSON field paths, Mixed) and explicitly mentioning pagination using a 'next' URL, providing critical behavioral traits that the structured data lacks.

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 highly dense and efficient, placing the primary retrieval purpose first and following it with all necessary technical implementation details (formats, pagination) in a single, well-structured paragraph.

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 lacking an output schema or annotations, the description is exceptionally complete. It covers the core function, the filtering capability, the detailed return formats, and pagination, giving the agent everything needed to anticipate the results.

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 schema description coverage at 0%, the description is extremely vital. It compensates fully by listing all supported page statuses (`same`, `new`, etc.) and explaining the complex nature of the tracking and results, which the schema cannot convey.

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 purpose is clearly defined as retrieving one specific monitor check and its page-level results. By specifying 'one monitor check,' it differentiates itself from presumed listing tools like firecrawl_monitor_list.

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 dictates the scope of use: retrieving detailed page-level results, and implies usage context through the available filters like page status. The focus on 'one check' guides the agent's intent appropriately.

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

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

No annotations are provided, so the description must carry the behavioral burden. It does say the call returns one page of check summaries plus pagination metadata, which is useful return-shape context, but it does not state read-only/safe semantics, auth or permission needs, rate limits, or default page size.

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 with no filler. The core purpose comes first, then the return shape, which is exactly the order an agent needs.

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

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

There is no output schema and no annotations, and all four parameters are undocumented in the schema. The description covers the return shape and paging concept, which helps, but it leaves the required id parameter and the offset/limit contract unexplained.

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 has to explain the four parameters. It only hints at limit ("bounded by a result limit") and status ("filtered by status"), and says nothing about what id identifies (the monitor) or how offset interacts with limit for paging.

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: "List historical checks for a monitor." That is clearly distinct from the singular sibling firecrawl_monitor_check and from firecrawl_monitor_get (config), though neither sibling is named explicitly.

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

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

The description mentions optional status filtering and a result limit, so usage is implied. But it never says when to use this instead of firecrawl_monitor_check for a single check, nor does it give any exclusions or prerequisites (for example, whether the monitor must exist).

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

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

With no annotations, the description carries the full burden. It does disclose real behavior: monitors schedule future network checks, can fire email/webhook notifications, retain predecessors for diffing, and return the created monitor. It omits credit cost, auth/plan requirements, and default scheduling behavior for a 15-parameter creation tool.

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

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

Two tight paragraphs, front-loaded with the core purpose before the form variants. Dense but nearly every clause carries information; the body-form enumeration is slightly list-like but 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 a 15-parameter creation tool with nested body, no annotations, no output schema, and zero schema descriptions, the description leaves too much undocumented — notably scheduling, notification targets, and result-limiting parameters an agent must set to create a useful monitor.

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 and only partly does: it explains goal (required in simple form), page/pages, queries and their precedence, and the body escape hatch. Ten of the fifteen parameters (name, email, timezone, maxResults, webhookUrl, includeDiffs, scheduleText, searchWindow, includeDomains, excludeDomains) get no mention at all.

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 ('Create a recurring scrape, crawl, or search monitor') plus its defining behavior (compares each check with its retained predecessor). This cleanly separates it from firecrawl_monitor_get/list/update/run and from the one-off firecrawl_scrape/firecrawl_search siblings.

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 distinguishes the simple form (page/pages or queries plus goal) from the advanced body form, and gives the precedence rule when queries and page/pages are both supplied. It stops short of saying when to prefer this over a one-off scrape/search, but the recurring framing implies it.

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

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

With no annotations, the description carries the behavioral burden and does well by disclosing that deletion is permanent, cannot be undone, stops the future schedule, and returns deletion status. It stops short of mentioning permissions, not-found behavior, or other error conditions.

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 tight sentences with no wasted words. The irreversible nature and schedule-stopping effect are front-loaded before the return-status note.

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 delete tool with no output schema and no annotations, the description covers the key risk and effect. It could be more complete by noting permissions requirements or behavior when the ID does not exist.

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%, but there is only one required parameter and the description says 'by ID,' which contextualizes it as a monitor identifier. It does not explain the ID format or where to obtain it, so it adds only minimal meaning beyond the schema.

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

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

The description states a specific verb and resource: permanently delete a monitor by ID. It also clarifies the effect of stopping the future schedule, which distinguishes it from monitor_update or monitor_get, though it does not explicitly name sibling alternatives.

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 the tool is for permanent deletion, but it does not explicitly state when to use it versus alternatives like updating or disabling a monitor. There are no exclusions or prerequisites 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the call is side-effect free ('does not run or modify'), but says nothing about what happens when the ID doesn't exist, whether it counts against credits, or how 'current state' is represented.

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 with zero waste: the action and return content come first, followed by the negative scope guarantee. Nothing is padded or repeated from the name.

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 one-parameter read tool with no output schema, the description covers purpose, identifier semantics, and the non-mutating guarantee, plus a hint at return contents ('configuration and current state'). Only error/not-found behavior and ID format remain uncovered.

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 schema description coverage at 0%, the schema documents nothing about the 'id' field, and the description only implies it identifies the monitor. That is the minimum needed to call the tool correctly, but format (UUID? slug?) and constraints are left unstated.

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) + resource (one monitor by ID) + scope (configuration and current state). The sentence 'This does not run or modify the monitor' cleanly separates it from firecrawl_monitor_run, firecrawl_monitor_update, and firecrawl_monitor_check.

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 makes clear this is the read-only single-record fetch and not an execution or mutation, which implicitly routes the agent away from monitor_run/monitor_update. It stops short of naming alternatives such as firecrawl_monitor_list for listing or firecrawl_monitor_checks for history, so there are no explicit exclusions.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the paged return behavior ('one page of monitor records and pagination metadata'), which is useful, but says nothing about permissions/scopes required, page-size limits, or what happens when offset exceeds the result set.

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 action and scope, with the return-shape note second. No filler; only mild redundancy between 'optional pagination controls' and 'pagination metadata'.

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 simple read-only list tool with two optional params and no output schema; the description covers scope, pagination, and return shape adequately. Missing only minor details like default page size, which is a small gap for this complexity level.

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 both parameters rely entirely on the description. The description identifies them as pagination controls, which adds real meaning over the bare 'limit'/'offset' names, but gives no defaults, maximum page size, or iteration guidance that the schema's extreme maximum (9007199254740991) makes non-obvious.

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 (List) plus resource (monitors) scoped to the authenticated account, which distinguishes it from firecrawl_monitor_get and the check-oriented siblings. It stops short of explicitly naming a sibling to disambiguate against, but the list semantics are unambiguous.

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

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

The phrase 'with optional pagination controls' hints at when pagination matters, but there is no explicit statement of when to use this instead of firecrawl_monitor_get (single monitor) or firecrawl_monitor_checks (check history). Usage is implied by the verb, not spelled out.

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

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

With zero annotations the description carries the full burden, and it does disclose two meaningful traits: the call starts external network work (a side-effecting trigger) and it returns the queued check object. It omits whether repeated calls queue duplicates, whether it is idempotent, and how the eventual result is retrieved.

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, both load-bearing: the first front-loads the action and its scope, the second covers the side effect and return value. No restatement of the tool name and no filler.

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

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

For a one-parameter trigger with no output schema and no annotations, the description covers purpose and immediate return but not the follow-up path (how to read the resulting check) or the id's origin. Adequate to select the tool, thin for invoking 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 0% for the single required parameter "id," so the description is the only place that could say what the id identifies (a monitor id, not a check id) and where to obtain it. It says nothing, leaving the most likely agent error — passing a check id or URL — unaddressed.

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 ("Queue an immediate check for a monitor") plus the distinguishing scope "outside its normal schedule." An agent can tell this triggers a check rather than reading one, though it never names the near-sibling firecrawl_monitor_check to sharpen the boundary.

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 condition "outside its normal schedule" implies when this is appropriate, which is real guidance. But there is no explicit when-not, no mention of cost/rate implications, and no pointer to firecrawl_monitor_check or firecrawl_monitor_checks for retrieving results, so the agent must infer the workflow.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does usefully disclose that edits apply to future scheduled checks rather than altering past results, and "Patch" implies partial-update semantics, but it says nothing about permissions, error behavior for an unknown ID, or whether omitted fields are preserved or reset.

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, both front-loaded: the action and identifier first, then the mutation surface and the forward-looking scope, then the return. 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?

A mutation tool with no annotations, no output schema defined in structured fields (it partially compensates with "Returns the updated monitor"), and a nested opaque body. It is adequate but leaves gaps around body structure and failure modes that an agent would want before calling it with an arbitrary object.

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% and the body is an untyped free-form object (additionalProperties: {}), so the description's field list is the only documentation of what can go in the body. That is real compensating value, but the `id` parameter is never described and no field types or value formats are given.

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 ("Patch an existing monitor by ID") and enumerates the mutable surface (name, status, schedule, targets, goal, judging, webhook, notifications, retention). That is enough to distinguish it from firecrawl_monitor_create, _get, _delete, and _list without opening the schema, though it never names those siblings.

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 verb "Patch" and by the note that changes affect future scheduled checks, which tells the agent this is a forward-looking edit rather than a retroactive one. There is no explicit guidance about when to prefer update over delete-and-recreate, or any prerequisite for the monitor existing.

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

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

With no annotations, the description carries the burden well: it discloses the two-phase upload handshake, that zeroDataRetention 'requires an eligible authenticated account' and should be omitted for anonymous keyless use, that redactPII requests content redaction, and that returns differ per phase (upload instructions vs parsed content, plus optional data.metadata.scrapeId). Gaps remain: no mention of credit/cost implications, file size limits, or failure behavior, which a 20-param no-annotation tool could still use.

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

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

Front-loaded with purpose and output modes, then organized into paragraph-per-concern (inputs, local vs hosted flow, behavioral flags, returns). Dense but justified for a 20-parameter tool; a few clauses, such as the scrapeId feedback note, are marginally more than an agent needs to invoke it.

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 sketches return shapes ('upload instructions for hosted phase one or parsed document content'), so more return detail would help. Given 20 parameters including two nested objects, the description also omits how formats, jsonOptions, and queryOptions relate to each other, leaving meaningful gaps for a tool of this complexity.

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

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

Schema coverage is only 30% across 20 parameters, so the description must compensate and only partly does. It clarifies filePath, uploadRef, pdfOptions.maxPages, redactPII, and zeroDataRetention semantics, but leaves many parameters undocumented in both places — formats, jsonOptions, queryOptions, onlyMainContent, includeTags/excludeTags, storeInCache, proxy, parsers, skipTlsVerification, removeBase64Images, conversationId, maxAge.

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 (parse) plus resource (one supported document) and enumerates the output artifacts (markdown, HTML, links, summary, targeted answers, schema-matched JSON) and supported input families (HTML, PDF, Word, RTF, OpenDocument, spreadsheets). It also explicitly routes remote URLs to the sibling firecrawl_scrape, so the agent can separate this from firecrawl_scrape/firecrawl_crawl without opening schemas.

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 and when-not-to-use: 'Remote web URLs belong in firecrawl_scrape.' It also spells out the branching operational flow — local MCP reads filePath directly, hosted MCP requires two calls (filePath for upload instructions, then uploadRef), and warns 'do not send both fields together.' That is a genuine exclusion rule an agent could otherwise get wrong.

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

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

With no annotations, the description carries the burden and does add real behavioral info: it is free and 'executes no provider,' clarifying it is a safe read operation with no side effects. It stops short of describing the response shape or pagination 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?

A single dense sentence front-loads the core action and follows with the limit/category qualifiers and the alternative reference. Efficient, though the clause stacking makes it slightly harder to parse than it could be.

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

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

For a simple two-parameter list tool with no output schema, the description covers action, scope, cost, and the alternative. Only the return format (e.g., what fields a provider entry has) is left implicit, 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 coverage is 100%, so both parameters are already documented, including that limit is 'in one catalogue page.' The description adds only marginal meaning ('catalogue order', 'in one category') beyond the schema, matching the baseline.

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

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

States a specific verb and resource ('List every Alexandria data provider') plus scope variants (all providers or one category). It differentiates from firecrawl_find_tools by pointing at it for browsing/contracts, though it doesn't distinguish itself from firecrawl_recommended_providers.

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

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

Gives clear usage context ('Used by the Firecrawl sidebar') and routes the agent to firecrawl_find_tools for browsing or contract reading. It lacks an explicit 'when not to use' beyond that alternative pointer.

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

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

With no annotations, the description carries the full burden and does well: it discloses the data source (team's own activity, 30-day window), the cost (free), and the absence of side effects ('executes no provider'). What it omits is auth/prerequisite behavior for an unconnected team and what an empty result looks like.

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 clauses, front-loaded with what is listed and scoped, then the client context and cost/safety note. No redundant restatement of the title or name.

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 no-parameter, no-output-schema read tool, the description covers provenance, scope, per-item reason, cost, and side effects. A brief note on return shape or empty-state behavior would close the 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to clarify beyond confirming no inputs are required. No contradiction with the empty schema.

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

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

States a specific verb and resource ('List data providers recommended') plus scope: the connected team's own Firecrawl activity over the last 30 days, each with a reason. The personalization language implicitly separates it from the generic firecrawl_provider_directory, though that sibling is never named outright.

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?

'Used by the Firecrawl sidebar' gives clear context for when this is appropriate, and 'free, and it executes no provider' signals the cost and safety profile an agent would want before calling. It stops short of explicitly contrasting with firecrawl_provider_directory or stating when not to use it.

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

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

No annotations exist, so the description carries the burden. It does disclose the return shape and markdown format, which signals a read-only retrieval, but it says nothing about failure modes (unknown/unresolvable IDs), external lookups, cost, or rate limits for a tool that clearly reaches out to source services.

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 with zero filler; the core action is front-loaded and the return-value sentence follows immediately. Nothing is repeated needlessly.

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 lookup with no output schema, the description is nearly sufficient: it names the accepted ID types and enumerates returned fields. The remaining gap is what happens on an invalid or unresolvable paper ID.

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 schema already lists the `arxiv:`/`pmcid:`/`pmid:`/`doi:` prefixed formats. The description only restates those identifier families, adding no format or normalization guidance 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?

States a specific verb and resource ('Retrieve canonical metadata for one paper ID') and enumerates the returned fields (title, abstract, authors, categories, source IDs, dates). It implicitly differentiates from firecrawl_research_read_paper by framing this as metadata rather than content retrieval, though it 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: the agent can infer this is the lookup to use when it already holds a canonical identifier. There is no explicit statement of when to prefer firecrawl_research_read_paper or firecrawl_research_search_papers, nor any note on what to do when the ID format is unknown.

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

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

With no annotations, the description carries the full burden: it does disclose the return shape ('matching passages or a notice when full text is unavailable'), which is genuinely useful failure-mode context. However, it says nothing about read-only safety, whether the retrieval is question-scoped ranking, or any limits beyond `k`; acceptable but not rich for an annotation-free tool.

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

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

Three short sentences, front-loaded with the core action, followed by the availability constraint and the return behavior. Slight redundancy between the second sentence and the schema's `k` description, but 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?

A three-parameter retrieval tool with no output schema and no annotations; the description covers what it does, the key availability limitation, and the shape of the response including the failure case. It only lacks guidance on fallback behavior when full text is unavailable (e.g., pointing to inspect_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 coverage is 67%: `paperId` and `k` are already well documented in the schema (including the default of 4), and the description largely repeats the `k` behavior. It does add the meaningful constraint that `paperId` only resolves for indexed papers, and it implies the semantics of the undocumented `question` parameter (relevance query), but does not define how matching works.

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 for a specific question — which is meaningfully distinct from sibling tools like firecrawl_research_inspect_paper and firecrawl_research_search_papers. It does not name or route against those siblings explicitly, so it stops just short of full differentiation.

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

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

The description gives a useful precondition (full text only for indexed papers) but never says when to choose this over firecrawl_research_inspect_paper (metadata) or firecrawl_research_search_papers (discovery). Usage is implied by the phrase 'relevant to a specific question' rather than stated as guidance.

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

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

No annotations, so the description must carry the behavioral burden. It discloses the return shape ('ranked candidates and the evaluated pool size') and mode behavior, but says nothing about cost, latency, or permissions/API-key needs for what is likely a paid research operation.

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

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

Three tight sentences, front-loaded with the tool's action, then parameter semantics, then the return contract. Every clause adds information; no repetition of the name 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?

No output schema exists, and the description supplies the return contract plus key parameter meaning. Gaps remain around k's default/max behavior and what the two-ID anchoring actually does to results, but the core call decision is fully supported.

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 only 20% schema coverage, the description carries most of the load and does so well: it defines seed_ids' cardinality and ordering, all three mode values, and intent's ranking role. It leaves k and the optional rerank flag unexplained (rerank only has schema text), so it nearly but not fully compensates.

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: find citation-graph candidates from seed papers. It distinguishes itself implicitly from sibling search_papers through 'citation-graph', but never names an alternative tool to route away from.

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?

Explains the seed ordering rule (first = primary, later = anchors) and defines each mode with when it applies: 'similar' for co-citation/bibliographic coupling, 'citers' for papers citing a seed, 'references' for papers cited by a seed. No explicit exclusion vs search_papers, but usage context is clear.

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

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

With no annotations, the description carries the burden and does disclose meaningful traits: results are ranked, and only canonical IDs, titles, authors, and abstracts come back (so no full text or PDFs). It omits any statement about corpus recency, rate limits, or whether filters are AND-combined at the result level — the schema covers the latter, but recency is unaddressed.

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, front-loaded with the what and corpus scope, then query strategy, then return shape. No sentence is filler and nothing is buried.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and noting ranking. With six params all documented, no annotations, and no destructive behavior to disclose, the only material gap is the absence of sibling routing and any note on corpus coverage/recency limits.

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; the description earns an extra point for adding real query-semantics guidance — that reformulating the same question in different framings changes the result set. It also summarizes the filter dimensions (author, category, date) without repeating syntax the schema already documents.

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 ("Search paper metadata and abstracts") with the corpus scoped explicitly (PubMed, bioRxiv, medRxiv, arXiv, other scientific sources), which differentiates it from generic siblings like firecrawl_search and firecrawl_developer_search. It also implicitly separates itself from firecrawl_research_read_paper by noting only metadata/abstracts are returned.

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 line "Several distinct framings of the same question surface different papers than a single query does" is genuinely useful invocation strategy, but the description never names an alternative or an exclusion condition (e.g. when to use firecrawl_research_read_paper for full text or firecrawl_research_related_papers for citation chaining). Usage is implied rather than 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?

With no annotations, the description carries the behavioral burden and does well: it discloses indexed-content freshness, `maxAge` staleness control, that success does not confirm currentness, profile loading without saving, scrape feedback IDs, and provider terms requirements. It still does not cover rate limits or broad failure modes, so it is strong but not exhaustive.

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

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

The most important information is front-loaded: what the tool does and when to use it. The later paragraphs add useful caveats about freshness, profiles, and Alexandria mode, though the description is dense and repeats the authenticated-session/provider-discovery idea somewhat.

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 29-parameter scraping tool with no output schema, the description is sufficient to select and call a basic scrape, and it explains the high-level return formats. It is not complete enough to confidently use many advanced parameters or understand full response shapes beyond the main content and Alexandria return behavior.

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 low at 28% across 29 parameters, so the description must compensate. It does add meaning for key parameters such as `formats`, `maxAge`, `profile`, and `alexandria`, but many advanced parameters like `proxy`, `waitFor`, `location`, `screenshotOptions`, and `onlyMainContent` receive no explanatory help.

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: scrape one URL and return its content in a chosen format. It also clearly differentiates this from siblings by naming `firecrawl_search`, `firecrawl_map`, and `firecrawl_crawl` for adjacent use cases.

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 when-to-use criteria: the request identifies a page and needs its content or defined fields. It also names the alternative tools and the conditions that select them, including search for additional sources, map for site URL listings, and crawl for collecting multiple 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?

With no annotations, the description carries the full behavioral burden and does so extensively: authenticated vs keyless behavior, default sources, Alexandria provider matches, government-result caveats, category restrictions, scrapeOptions billing/fetch behavior, and conversationId persistence. These are material operational details beyond 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?

The description is front-loaded with purpose and primary usage, then structured by auth mode, source types, and category-specific behavior. It is necessarily long for a 16-parameter tool, but some repetition around Alexandria defaults and authenticated source behavior 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?

Given the tool's complexity and lack of an output schema, the description is complete enough for invocation: it explains return groups, data.tools vs data.web, category fields, usage metadata, and optional search feedback IDs. It also covers auth-dependent behavior that changes what results appear.

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 description adds substantial meaning for high-risk or non-obvious parameters such as sources, categories, domainTools, toolDetail, highlights, scrapeOptions, and conversationId. However, several parameters such as tbs, limit, filter, location, and enterprise receive no explanation in either the description or schema, leaving some gaps.

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

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

The description opens with a specific verb and resource: search web, news, or image sources and return ranked results with highlights. It also distinguishes the tool from siblings by naming firecrawl_scrape, firecrawl_find_tools, firecrawl_gov_search, and the firecrawl_research_* family.

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 when-to-use guidance: current information, listing businesses/people/products/jobs/events, and choosing providers over scraping for many records or exact figures. It also states alternatives and exclusions, including scraping only when excerpts are insufficient, using developer/gov/research categories, and preferring dedicated tools for gov/research surfaces.

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

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

With no annotations, the description carries the full burden and does: it discloses the refund behavior (1 credit for eligible first feedback, subject to a team daily cap), idempotency per search ID, eligibility restrictions, array size caps, and the response contents (refund applied, submission and daily-cap status). The 'unlisted results are treated as not useful' warning is a genuine behavioral consequence an agent could not infer from 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?

Three tight paragraphs that front-load purpose, then eligibility/refund, then field mechanics; the exhaustive-listing warning is well placed at the end. Some of the `valuableResults` wording duplicates the schema's property description almost verbatim, which is slightly wasteful but reinforces an easy-to-misuse field.

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, yet the description states what the response reports (refund status, submission status, daily-cap status), and with no annotations it fully covers mutation semantics, idempotency, and cost implications. Minor gaps remain around `conversationId` threading and when to supply `querySuggestions`.

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 only 43%, and the description compensates for the highest-risk fields: it explains `valuableResults` position/source pairing with the per-group numbering caveat, and warns never to duplicate a result in `valuableSources` (reserved for URLs not among returned results), plus per-rating semantics for `missingContent` and `querySuggestions`. It says nothing about `conversationId` or `querySuggestions` usage beyond the rating rules, leaving part of the coverage gap open.

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 ('Records schema-validated quality feedback') and anchors it to a concrete input ('a prior `firecrawl_search` UUID `searchId`'). That anchor also distinguishes it from the generic `firecrawl_feedback` sibling without needing 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 conditions for each rating value ('good' requires a valuable result or source, 'partial' either or a missingContent entry, 'bad' at least one missingContent or a query suggestion) plus eligibility limits (successful searches only, within the feedback age window). It never contrasts itself with the sibling `firecrawl_feedback`, so a 4 rather than 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth prerequisite (connected Firecrawl account), that the action is an interactive UI surface rather than a data return, and that it can attach context to a conversation (a side effect). It doesn't say what the call returns or what happens if the account isn't connected, 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?

Three short sentences, front-loaded with the action and capabilities, then the prerequisite, then the sibling routing. Every sentence carries distinct information with no repetition of the name 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 zero-parameter, no-output-schema UI tool, the description covers purpose, prerequisite, and alternative, which is nearly everything an agent needs. A small gap remains around outcome (does it return a URL/handle, and does it fail without a connected account), but this is minor given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4; there are no argument semantics for the description to explain. It correctly adds no redundant parameter talk, though it also can't be credited with compensating 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?

States a specific verb and resource ('Open the Firecrawl sidebar') and enumerates three concrete capabilities: browsing Alexandria providers, attaching tool context to a conversation, and viewing credits/usage. It is clearly separable from siblings like firecrawl_credit_usage or firecrawl_provider_directory because it is the interactive-UI entry point rather than a data endpoint.

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 an explicit alternative and the condition that selects it ('Use firecrawl_credit_usage for data-only reporting'), and states the prerequisite ('Requires a connected Firecrawl account'). It stops short of saying when an agent should prefer opening the sidebar at all (e.g., only when the user wants interactive browsing), leaving that inference to the caller.

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