MeshArc

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

Annotations cover safety (idempotent, non-destructive) but the description adds substantial behavioral context beyond them: per-page credit costs (1-4, refused pages free), synchronous waiting with a time budget, hosted crawls returning a job retrievable via get_job, idempotent repeat-call behavior, and a one-day retention window. This is far past what annotations alone convey.

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

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

Purpose and alternatives are front-loaded and every sentence carries information. It is, however, a dense run-on block with several clauses chained by semicolons, which slightly hurts scannability for an agent parsing it quickly.

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 no output schema, the description explains the return shape (index of pages plus excerpts capped at 60,000 characters), how to page through one page via get_job with url vs cursor, and the crawl_id retention handoff. An agent has enough to call and consume the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents url, limit, config, max_depth, and include/exclude paths thoroughly. The description reinforces `limit` and the crawl_id return but adds no parameter syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (crawl) and resource (site from a start URL), including the mechanism (following links, reading sitemap, up to `limit` pages) and the key scoping outcome (returns an index without creating a project). It explicitly distinguishes itself from scrape_urls and create_project. An agent can select it correctly without opening the schema.

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

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

Gives explicit when-to-use ('whose page URLs you do not know') and when-not, naming the alternatives: scrape_urls for known URLs, create_project to watch a site over time, keep_crawl_as_project to persist this crawl. Nothing is left to inference.

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

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

Beyond the annotations, it discloses important behavior: creation reads robots.txt and sitemaps but fetches no pages, each run spends credits per page, and creation is refused when the plan's project limit is reached. It also explains the return value enough to point the agent to start_run.

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

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

The description is a compact paragraph that front-loads the core purpose and then adds usage, side effects, limits, and return behavior with no filler. Every sentence carries actionable information for an agent.

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

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

Despite having no output schema, the description explains what is returned (the project and its id for start_run). It also covers prerequisites, alternatives, operational cost, and plan limits, which is complete for a high-impact creation tool.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters in detail. The description adds useful context about the project lifecycle but does not add syntax or per-parameter meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource: creating a project that watches a site over time, crawling on a schedule and comparing runs. It also names the key siblings it is not (crawl_site, keep_crawl_as_project, list_projects), so an agent can distinguish it 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 explicitly says when to use it (monitor or track a site) and when not to use it (one-off reads should use crawl_site, and keep_crawl_as_project can convert later). It also adds a concrete precondition: check list_projects first to avoid adding the same site twice.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description adds context beyond them: 'Free, and it fetches nothing' (cost and no network/side effects) and 'keys are exact and guessed names are refused' (validation behavior that silently fails otherwise). It does not describe the return shape in depth, but the behavioral profile is well covered.

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 purpose, then the when-to-use rule, then sibling disambiguation, then the cost note. Dense but every sentence earns its place; slightly long for a zero-parameter tool.

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 parameters, the description carries the full burden and does so: it says what the response contains (each key with meaning and default, valid schedules, path glob behavior). An agent knows both what the tool is for and what it will get back.

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. The description does not need to explain argument semantics, and the empty schema is consistent with a pure reference-lookup tool.

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 and resource: lists the project settings an assistant can set, plus valid schedules and path glob semantics. It explicitly separates itself from the sibling get_project ('describes settings in general; get_project shows the values one project has'), so an agent can route without opening either schema.

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

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

States exactly when to read it: before create_project, update_project, or a `config` argument, and specifically whenever the request names a section, schedule, format, limit or behaviour. It also gives the reason (keys are exact and guessed names are refused), which is actionable gating guidance with a named alternative.

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

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

Annotations only cover safety flags (readOnly/openWorld/idempotent/destructive), so the description carries real weight and delivers: the fetch ladder (plain http first, browser only when needed or render_js is 'always'), credit cost 1-4 plus +1 for screenshots, the 12,000-char caps, and that browser actions run before the read. What it omits is failure/timeout behavior and auth requirements, but coverage is well above the annotation floor.

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 return payload before the routing guidance, and every clause carries information (cap sizes, cost, ladder). The actions enumeration is dense but relevant; it is long without being padded.

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, the description compensates by describing the return shape in detail, and it supplies the cost, fallback, and browser-action behavior an agent needs to call correctly against a large sibling set.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic detail: it explains render_js 'always', the actions vocabulary (click, type, select, press, wait, scroll, 'until_gone', each), and that a parse_documents key in config overrides the top-level flag.

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+resource ('Fetch one URL ... return the whole page') and enumerates exactly what comes back (config formats, raw html capped at 12,000 chars, head, extracted fields, images, engine; no link list). It distinguishes itself from scrape_urls and get_page by name.

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

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

Gives explicit when-to-use ('a single page that needs browser steps, structured fields or a settings trial before create_project') and routes two alternatives with their selecting conditions: scrape_urls for plain content of known URLs, get_page for an already-stored page without fetching.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: removals are suppressed when crawl coverage drops under 90% so a blocked crawl is never reported as site loss, the first run is a baseline with nothing to compare, and results are capped at 200 entries per list. These are non-obvious edge-case semantics an agent must know.

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?

Dense but front-loaded: the core operation leads, then the returned lists, then routing to siblings, then edge-case caveats. Every clause carries information (limits, suppression rule, baseline rule, cost) with no filler.

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

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

With no output schema, the description must characterize the response, and it does: entry types, per-list cap of 200, coverage, and the run-provenance caveat. Combined with the baseline and suppression rules, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters are already documented, including run_id's null default and provenance. The description restates the run_id fallback ('last finished run unless run_id is given'), which adds emphasis but little new syntax or format information. 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 ('report what changed in a project run') and enumerates exactly what is reported: pages added/modified/removed, head-field changes, and run coverage. It distinguishes itself from list_pages and get_page by name, so an agent can pick it 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 the direct use case ('answer what changed on the site') and explicitly routes to alternatives with their conditions: list_pages shows every page regardless of change, get_page shows one page's text and versions. That is when-to-use plus when-not-to-use in one sentence.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, but the description adds real behavioral context: it is free, reads only stored results, never fetches, and returns the original tool's result once finished versus status/counts while running. It does not cover auth needs or any rate/expiry limits, so it stops 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?

Front-loaded with the core purpose and trigger, with the crawl-pagination and get_page routing details following. It is dense and runs long for one paragraph, but every sentence carries information an agent needs; no filler is present.

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, the description carries the return-value burden and does so by explaining the two states (running: status and counts; finished: same result as the originating tool). That is nearly complete, though the literal shape of a finished result is conveyed by analogy to the original tool rather than specified.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds semantics the schema does not: `url` reads one page in full even mid-crawl, and `cursor` reads the next window of pages, tying both to the crawl reading flow. `kind` and `project_id` semantics are largely already in the schema, so this is an increment rather than a full rewrite.

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 ('check on a job', 'return the same result the original tool would have given') and explicitly maps each job kind to the sibling that produced it (crawl_site, start_run, recrawl_pages, scrape_urls). An agent can distinguish it from every sibling without opening a schema.

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

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

It states the trigger condition precisely ('Call it when a tool answered with status "running" and a job'), rules out the wrong action ('calling the original tool again is not needed and would not start a second job'), and routes elsewhere when appropriate ('For a project's stored pages use get_page instead'). This is explicit when-to-use, when-not, and alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds behavior not derivable from them: body truncation at 12,000 characters, per-run vs newest-copy selection, 404 semantics for unstored URLs, and the guarantee that it never hits the network. That is meaningful operational detail for an agent deciding how to source a page.

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 what the tool returns before routing guidance, and every clause carries information (scope, alternatives, cost, failure mode). The opening sentence is dense with an inline parenthetical and a list, which slightly taxes readability, but there is no filler.

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

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

There is no output schema, so the description carries the return-value burden, and it does so by enumerating the returned sections and their truncation behavior. Combined with the routing rules and 404 case, an agent has everything needed to call this correctly without opening a sibling.

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

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

Schema description coverage is 100%, so the schema already documents url, run_id, and project_id with their formats and sourcing. The description reinforces the distinction between a run-specific copy and 'the newest copy across the project's recent runs' via 'its versions across runs', but adds no syntax or format detail the schema lacks.

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 ('Read one page a project run stored, in full') and immediately enumerates what the payload contains: markdown bodies (capped at 12,000 chars), head fields, extracted fields, and versions across runs. It distinguishes itself from siblings by naming search_pages/list_pages, get_job, and extract_url with the exact conditions that select each.

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

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

Explicit when-to-use ('Use it when you know the page's URL'), explicit prerequisites (list_pages or search_pages finds the URL first), and explicit alternate routes for crawl_site crawls (get_job with url) and live copies (extract_url). It also states the failure case: a URL the run did not store answers 404.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes further with operational traits: it is free, fetches nothing (no upstream crawl triggered), unknown or hidden projects return 404, and the webhook signing secret is withheld. These are exactly the behaviors an agent cannot infer from structured fields.

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

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

Front-loaded with the core purpose, then routed alternatives, then behavioral caveats, then the withheld-secret note. Dense but every clause carries distinct information and none is redundant with the schema or annotations.

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, the description compensates by enumerating the returned fields (config, schedule, retention, coverage, last run) and disclosing the one field withheld. Error behavior (404) is also covered, so an agent has everything needed to call and interpret 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?

Only one parameter and schema description coverage is 100%, with the schema already explaining that project_id comes from list_projects or create_project. The description adds no format, syntax, or lookup guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Read one project in full') plus the exact scope of what is returned: settings, schedule, retention, coverage, last run. It also names the siblings it differs from (list_projects, get_changes, list_pages), so an agent can disambiguate 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?

Explicit when-to-use: read it before update_project to see the values being changed. Also names the lighter alternative (list_projects) for finding projects and points to list_pages/get_changes for run findings, covering both the positive and negative cases.

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

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

Annotations only cover the safety profile (non-read-only, non-idempotent, non-destructive), while the description adds the traits that actually matter: no refetching, no credit cost, the crawl's pages becoming the first run, the day-long expiry if unused, the plan project-limit interaction with a named plan_limit refusal, and the return value's id being consumed by other project tools.

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

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

Front-loads the core transformation, then layers usage routing, cost/expiry caveats, and the return contract in roughly priority order. It is dense but every clause carries information; only the length keeps it short of a 5.

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

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

Despite having no output schema, the description states what is returned (the new project and its id, used by other project tools) and covers cost, expiry, and plan-limit failure. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters (name, crawl_id, schedule) are already documented in the schema, including crawl_id's provenance and the credit cost of scheduled runs. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

Specific verb and resource ('Turn a crawl_site crawl into a project') with the scope of what that produces ('the site is watched over time'). It explicitly differentiates itself from create_project, so an agent can choose between them without opening either schema.

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

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

Gives a clear trigger ('Use it after crawl_site when the site is worth watching') and names the alternative for the contrasting case ('to start a watched site from scratch use create_project'). Both when-to-use and when-to-use-something-else are stated.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it is 'Free', it 'reads only what is stored: it never fetches the site', and it caps results at 500 rows. It stops short of describing ordering or truncation behavior beyond the row cap.

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

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

Front-loaded with the core action and scope, and every clause earns its place (fields returned, row cap, alternatives, edge case). The opening sentence is long and packs the returned-field list and default-run rule together, which costs a little readability.

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 (url, status, depth, word count, last changed, runId) and the 500-row cap. Combined with the default-run resolution and the no-pages edge case, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so run_id and project_id are already documented, including the 'leave empty for last finished run' default. The description restates the default resolution but adds no format or reference detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (lists the pages a run stored) and immediately scopes it ('the last finished run unless run_id is given'). It also names the sibling alternatives (get_page, search_pages, get_changes) so the agent can tell it apart without opening other 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?

Explicit when-to-use ('see what a crawl covered or to pick a URL') and explicit routing to alternatives with the condition that selects each: get_page for full content, search_pages for text lookup, get_changes for diffs only. Also states the empty-project edge case ('no finished run answers with no pages').

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine context beyond them: it is free, fetches nothing (reads only stored data), and is scoped by API key permissions. It stops short of noting pagination or result-size behavior, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with what is listed, then routing guidance, then the read-only/permission caveat. No sentence is filler.

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

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

Zero-parameter read tool with annotations and an output schema; the description still covers routing, cost, data freshness ('reads only what is stored'), and key-scoping. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description's field list describes the response shape rather than inputs, and with an output schema present it adds no parameter meaning to compensate for.

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

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

Specific verb + resource ('List every project in the workspace') with the returned fields enumerated, and it explicitly distinguishes itself from get_project ('gives one project's full settings'). An agent can separate it from every sibling without opening a schema.

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

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

Gives concrete when-to-use conditions: call first to obtain a project_id for other project tools, or to check whether a site is already watched before create_project. It also names the alternative (get_project) and the condition that selects 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?

Goes well beyond the annotations: it discloses the cost model (1 credit per sitemap file read, usually 1 total, never per URL), the non-fetching behavior, and the specific limitations (no content, misses undeclared pages). The credit side effect also explains why readOnlyHint is false despite the discovery-only behavior, so there is no contradiction.

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

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

Front-loaded with the core purpose and packed with useful detail in a small footprint; the em-dash-heavy run-on sentence is dense but every clause earns its place. Slightly harder to scan than two clean sentences.

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

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

With no output schema, the description supplies the return shape (discovery method, totals, up to `limit` URLs, section names) as well as cost and coverage caveats. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description restates `limit` ('up to `limit` URLs') and adds that totals still count all URLs, but does not mention the `search` filter or add syntax beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource ('List every URL a site declares in its sitemaps') with the mechanism named (robots.txt, well-known paths, index files walked to children). It is immediately distinguishable from siblings like crawl_site and scrape_urls, which it explicitly says do something else.

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 ordering guidance ('Use it first... before crawl_site or create_project') plus clear exclusions: it cannot read page content (scrape_urls or crawl_site do) and misses pages a site links to but does not declare. Both when-to-use and when-not-to-use are covered with named alternatives.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive. The description adds valuable context beyond annotations: credit cost (1-4 per page), the 409 refusal condition (another run queued/running), URL host constraint, and the follow-up workflow (get_job with kind 'run', then get_changes). It does not explain what happens if some URLs fail or the exact shape of the returned run, but the coverage is strong.

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

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

Front-loads the core action, then scenario, alternatives, cost, constraint, failure mode, and return/workflow. Every sentence earns its place with no redundancy.

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

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

For a mutation tool with 2 well-documented params and annotations covering safety profile, the description fills remaining gaps: cost, failure condition, host constraint, and the follow-up workflow using sibling tools. An agent has everything needed to call this correctly and interpret the result.

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 defines both parameters well. The description reinforces the URL constraint ('must be on the project's site') and the credit-per-page cost, adding value beyond the schema's bare '1 to 500 full URLs on the project's site'.

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+resource+scope: 'Fetch specific pages of a project again now, as a small run of their own...compares just those pages with the last full run.' Explicitly distinguishes from siblings start_run ('re-crawls everything') and extract_url ('reads a page outside any project').

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

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

Names the intended scenario ('check a few pages you expect changed without crawling the whole site') and names two alternatives (start_run and extract_url) with the conditions that select them. Nothing is left to inference.

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

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

Goes well beyond the annotations by disclosing credit economics (1 plain fetch, 4 browser render), that refused pages are free, that a single URL answers in-request while a list waits for the batch, the 60,000-character excerpt limit, and that a hosted batch still running returns a job for get_job with repeat-call idempotency. This is rich operational context that the annotations alone do not convey.

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

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

Purpose and the sibling routing are front-loaded, and every sentence carries information about cost, batching or job behavior. It is dense and drifts into long run-on sentences at the end, but there is little pure filler to cut.

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, the description still explains the return shape (index with excerpts capped at 60,000 characters) and the asynchronous job path for large hosted batches. Combined with full parameter coverage, an agent has everything needed to call and handle this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents urls, config, formats and parse_documents in detail. The description repeats the 'markdown by default' default and echoes the batch/excerpt behavior but adds no new syntax or format guidance beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource (fetch a list of known URLs, 1 to 500) plus the key scope fact that no project is created. It explicitly distinguishes itself from three named siblings (extract_url, crawl_site, map_site), 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 explicit when-to-use-which routing: extract_url for one page with every format or browser steps, crawl_site for finding pages via links, map_site for listing URLs without fetching. Nothing about alternative selection is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: it scans stored copies rather than fetching the site, so it is free and only as fresh as the run. It also discloses the rawHtml/selector precondition and that a missing-html situation is reported explicitly rather than as zero matches.

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 core purpose and then the disambiguation and the freshness/precondition caveats. No filler or repetition of what the schema or annotations already declare.

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, the description still characterizes the result (matching URLs plus pages scanned) and the degenerate case where html was not retained. Combined with full parameter coverage and annotations, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: selector mode depends on the run having preserved rawHtml, and run_id defaults to the last finished run. The quoted-phrase and CSS/XPath syntax details remain schema territory.

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 which pages of a project run contain some text or an element') plus the return shape (matching URLs and scan count). It explicitly distinguishes itself from the siblings list_pages and get_page, so an agent can route without opening a schema.

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

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

Gives an explicit use case ('locate pages by what they say or contain') and names the two alternatives with their roles: list_pages lists every page, get_page reads one in full. It also states the default run scoping (last finished run unless run_id is given), so the when-to-use decision is fully specified.

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

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

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive), and the description layers on cost (1–4 credits per page), budget-exhaustion behavior (stops and keeps what it read), and the 409/402 refusal conditions. This is far beyond what the annotations alone convey.

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

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

Front-loads what the tool does, then usage routing, then cost/error semantics, then return behavior. Every clause carries information; no filler.

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

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

With no output schema, the description still explains the return shapes (queued run, finished run, or a job for hosted timeouts) and points to list_pages/get_changes for reading results. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: 'with wait it returns the finished run, except hosted, where a run still going after the time budget comes back as a job for get_job.' That extra hosted-mode nuance materially changes how the wait parameter behaves.

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

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

States a specific verb and resource ('Crawl a project's site now with its saved settings, outside its schedule') and immediately distinguishes itself from recrawl_pages and crawl_site by name. An agent can identify the exact operation without opening the schema.

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

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

Gives explicit triggers ('after create_project or update_project, or when fresh results are wanted') and names the alternatives with the conditions that select them: recrawl_pages for a few pages, crawl_site for sites with no project. Nothing is left to inference.

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

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

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): it discloses merge semantics ('only the keys given are replaced, the rest stay; a replaced value is not kept'), cost behavior ('no credits are spent now'), deferred effect ('the next run uses the new settings'), and a side effect ('starts a fresh comparison baseline'). These are exactly the traits an agent needs and the annotations do not convey.

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

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

Front-loads the core action and then layers constraints in a single dense paragraph; every clause earns its place. It is slightly packed with stacked semicolons, which costs a little readability but not substance.

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, but the description states 'Returns the updated project.' Combined with the merge/cost/baseline behavior, everything needed to call this mutation tool correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds the overwrite nuance ('a replaced value is not kept') and points to describe_project_config for valid config keys, which the schema does not say. That is real added meaning, though most per-parameter detail is already in the schema.

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

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

States a specific verb (Change) and resource (existing project's name, schedule or settings), and explicitly scopes it against siblings: 'to start a different site use create_project instead' and 'Call get_project first'. An agent can distinguish this from create_project and get_project without opening a schema.

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

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

Gives explicit prerequisites ('Call get_project first to see the current values, and describe_project_config for valid keys') and names the alternative with its selecting condition ('to start a different site use create_project instead'). When-to-use and when-not-to-use are both covered.

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