writ-mcp

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

Annotations flag destructiveHint=true/openWorldHint=true, and the description adds rich context beyond them: confirm_write 'changes real data, only when authorized', sensitive fills must carry data_key, secrets are held server-side, the 2FA code is minted server-side and never shown, and which actions are/aren't recorded as replay steps.

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 given the tool's complexity most sentences carry real information. However it is a very long, dense wall of text with heavy inline action enumeration that could be tightened; structure is functional but not economical.

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

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

For a high-complexity, open-world, destructive browser automation tool with no output schema, the description covers recording semantics, probe vs drive actions, error recovery, tabs/files/2FA, and credential handling — essentially everything an agent needs to invoke it safely.

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 materially enriches the opaque `actions` array by illustrating action shapes, the {{placeholder}}/inputs contract, and data_key secret handling — more than the schema's terse 'ordered action objects' conveys.

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: 'Run one batch of actions on an open browser session and get the fresh page back.' It immediately frames the agent's role ('YOU are the brain') and distinguishes batch interaction from compose/network 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?

Explicit when-to-use rules abound: end the batch after page-changing actions, use compose actions when writ_browser_compose is absent, choose granular SEE probes before get_dom, and a clear decision tree for twofa errors and when to call writ_browser_ask_user instead of guessing.

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?

Even with annotations present, the description adds rich behavior the annotations cannot convey: the session pauses, the user is notified in-app and by email and controls the live page, the call holds up to 60s, the three possible statuses (answered / waiting_for_user / expired), and that with kind='twofa' the code is entered server-side and never reaches the agent. This is well beyond the readOnly/idempotent hints.

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, triggers, and prohibitions are front-loaded in the first two sentences, and each subsequent clause carries actionable information. The description is dense and long (roughly a paragraph and a half), which is justified by the branching logic, though it could be trimmed slightly without loss.

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 contract itself (the three statuses and their payloads, including 'entered' for twofa) and the timing/polling behavior. Combined with the error-driven usage triggers, an agent has everything needed to invoke and re-invoke 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 coverage is 75%, so the schema already documents most parameters (including the kind enum and wait_seconds bounds). The description nonetheless adds real meaning: it warns not to use kind='question' to obtain a one-time code, and explains that kind='twofa' returns 'entered' rather than the code. session_id re-use on 'waiting_for_user' is also clarified.

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 ('Ask the WRIT USER ... to step in on an open browser session') and enumerates the concrete cases it covers: CAPTCHA/security check, one-time 2FA code, or an undecidable question. It clearly separates this human-in-the-loop tool from the autonomous siblings (writ_browser_act), 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?

Explicit triggers are given (writ_browser_act returns security_check with auto_solved false; twofa_mint_failed / twofa_no_persona) plus an explicit when-not: a 2FA code 'is NOT a first-resort ask' until the agent has tried switching/resending the method. Alternatives (verify on the page and switch the twofa method) are named, and the prohibition on clicking CAPTCHAs yourself is 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 flag destructiveHint=true and idempotentHint=true, and the description goes well beyond them: unsaved work is auto-saved as a workflow first, the reply names it, it may be an inactive draft if it would not replay, and build-bound sessions are settled or marked cancelled. This is exactly the mutation-side effect an agent could not 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?

Three dense sentences, front-loaded with the action and reason, and each clause adds real information (auto-save, discard, build-bound handling). Slightly compressed in the final sentence, but nothing is padding.

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

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

No output schema exists, yet the description still explains what the reply contains (the workflow name) and how the session is finalized. For a destructive, non-idempotent-looking close operation with no annotation-level detail on data retention, this is complete.

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%: discard is documented in the schema and the description reinforces it meaningfully ('Pass discard=true to close without keeping anything', default false). session_id is undocumented in both, but its meaning is unambiguous. The description adds the consequence of discard that the schema only hints at.

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 — 'Close an open browser session' — with clear scope (session is not being reused, or is being abandoned). An agent can distinguish it from session-management siblings, though no sibling is named to draw an explicit contrast.

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: task finished and no reuse intended, or abandoning a session, with the rationale that an open cloud browser keeps consuming execution time. It does not name an alternative tool for cases where the user does want to keep going, so context is clear but exclusion logic is left implicit.

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?

Well beyond the annotations (destructiveHint/openWorldHint/idempotentHint), the description discloses that every function is live-tested on definition, that a failed test 'keeps NOTHING', that the build never sends writes while a real run does, that a save is refused if a {{name}} is undeclared, and that credentials are never inputs. These are exactly the behavioral traits an agent needs and are not inferable from the hints.

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, then WHEN YOU NEED IT, OPERATIONS, FASTEST PATHS and DETAILS, which is strong structure for an eight-operation tool. It is nonetheless extremely long, and the 'live-tested / failed test keeps NOTHING / redefine with the SAME name' point is repeated in both FASTEST PATHS and DETAILS, costing some conciseness.

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 covers return shape (functions callable by name, api-docs endpoint), save behavior, draft inspection via `list`, and per-operation argument semantics for all eight operations. Given the complexity and nested payload, almost nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 67% and the payload schema is already richly documented, so the baseline is high. The description nonetheless adds real semantic depth the schema lacks: {{name}} placeholder semantics, {{secret:}}/{{cookie:}}/{{extracted:}} references, response_extractions spec formats, and then_save testing behavior. Some of this overlaps the existing payload description, keeping it just shy of a 5.

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

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

The opening line states a specific verb and resource ('AUTHOR the workflow being built in an open browser session') and immediately frames the tool's role versus a plain recording. It explicitly names sibling tools (writ_browser_act, writ_browser_context, writ_browser_network, writ_browser_save) and distinguishes their roles, so an agent can separate this from neighbors 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?

The 'WHEN YOU NEED IT' block gives explicit when-to-use (expose named functions, add descriptions/defaults, add steps the recorder cannot see) and when-not ('not for a plain recording'), plus the alternative pattern for that case. FASTEST PATHS routes to specific siblings with concrete conditions, covering both selection and exclusion.

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

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

Annotations already establish readOnly, non-openWorld, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds that section=lists scans at no AI cost and is live-tested, and that map output is evidence to verify — useful context beyond annotations. It does not describe pagination behavior for non-policy sections, output format, or rate limits, leaving some behavioral gaps.

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?

Information-dense but front-loaded with the section definitions before procedures. However, the middle section is a run-on that jumps between the 'for ONE list/search API' workflow and section=lists scanning, making it harder to parse. Could be tighter without losing essential details.

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 no output schema and a complex tool with five distinct sections, the description is substantially complete: it covers all section modes, their purposes, and the integration path with writ_browser_compose. It lacks detail on offset/max_chars paging behavior and exact output shape, but for a multi-modal read tool it is mostly sufficient.

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

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

Schema coverage is 75%, so most parameters are already documented in the schema (section enum, offset, max_chars). The description adds meaning to section values (what page vs map vs lists vs explorer vs concierge_api returns) that goes beyond the schema's terse enum listing. Baseline 3 is appropriate given the schema does the heavy lifting and the description adds some section semantics.

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) and resource (browser session context), then enumerates the sections and their distinct outputs — live page state, build map, list scanning, and policy reference. This is far more precise than the sibling read tools like Writ_browser_network or writ_browser_sessions, which read different facets of a session.

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 tells when to use each section: section=lists is for scanning results pages and must be read BEFORE probing by hand; section=map is for the build; policy sections are for unusual flows and not a prerequisite. Directs the agent to pass define_function to writ_browser_compose, naming a sibling and the handoff.

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 the description adds real behavioral context beyond them: indices are stable for the session, only oldest calls age out, and a stale index errors rather than silently returning a different call. It also discloses that held credential values are replaced with placeholders in output, which is important for interpretation.

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?

Information-dense and front-loaded, with the core purpose stated first and operational detail following. It is on the long side and slightly paragraph-heavy, but nearly every sentence carries load; a minor trim would make it tighter.

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 7-parameter, two-operation tool with no output schema, the description covers both operations' return shapes (detail returns method, url, request/response bodies), the staleness edge case, the capture prerequisite, and credential redaction. Nothing an agent needs to call it correctly is missing.

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

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

With 71% schema coverage the schema already documents most parameters, but the description adds meaning: operation semantics, that query/method filter the search results, and that index refers to the stable call index from a prior search. It does not mention the offset/max_chars pagination behavior of the search window, leaving a small 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+resource (search/read the network requests the live page made) and frames the payoff against scraping HTML, which clearly separates it from siblings like writ_scrape or writ_crawl_site. It also names the two operations the tool supports, so an agent knows the tool's surface 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 workflow: if nothing is captured, run capture_network via writ_browser_act first, and to catch a POST, trigger the action then capture. It also routes output to writ_browser_compose's define_function via from_index, so the agent knows where this tool sits in the broader flow.

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

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by disclosing that saving closes the browser, that the saved workflow is ACTIVE at zero AI cost, and that the save is REFUSED with reasons when a step cannot resolve at run time. The allow_no_data refusal/warning semantics add real behavioral detail. It does not explicitly restate the destructive/irreversibility angle beyond 'closes the browser,' so it lands 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 action and outcome in the first sentence, with consequences and refusal conditions following in a logical order. It is dense with parenthetical tool cross-references, which is useful routing information but pushes the prose near the limit of what one tool description should carry.

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 covers the mutation's side effects, activation state, refusal behavior, and follow-on tooling — enough for an agent to call it correctly. The one gap is the return value: it never says what a successful save yields (e.g. a workflow id) or what the refusal response looks like.

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 60%, and the description compensates on the ambiguous parameters: it clarifies keep_open means the browser stays open (default closes it), that name defaults to the goal, and it expands the allow_no_data refusal-vs-warning semantics well past the schema text. session_id and description remain undocumented in both places, which caps it below 5.

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

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

Specific verb (save) plus resource (open browser session) plus the exact transformation: composed session materializes into a replayable workflow and the browser closes. It distinguishes itself from siblings by naming writ_browser_compose as the producer and writ_run_workflow / writ_pin_workflow_tool as the consumers, so an agent can place it in the lifecycle without reading 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?

Gives an explicit gate: 'Only save once the task actually worked on the live page — verify first,' plus refusal conditions tied to unresolvable references. It also routes to the correct downstream tools for running, scheduling, exposing, and documenting the saved workflow. What is missing is a direct when-not-to-save rule versus sibling tools like writ_export_data or writ_record_website.

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

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

Annotations already cover read-only/idempotent/non-destructive safety, so the bar is lower; the description adds real value by disclosing that sessions stay warm, parked on a page, and keep billing while open, plus the resumable flag concept. It stops short of describing pagination or ordering of results, 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?

Front-loads the purpose and the resume rationale before naming alternatives; every clause carries instruction. Slightly dense with the billing aside, but nothing is filler.

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

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

No output schema exists, so the description usefully enumerates the returned fields (id, status, resumable flag, current url, goal), and it supplies the workflow context needed to act on the result. Nothing an agent needs to call or use the tool 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% and both parameters (limit, include_closed) are documented there, so the schema does the heavy lifting. The description never references limit or include_closed, adding nothing beyond the schema — the baseline 3 when coverage is high.

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 (list open cloud browser sessions) with account scope, and explicitly differentiates itself from siblings by naming writ_browser_use, writ_browser_act and writ_browser_context. An agent can select it vs. those tools without reading 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 ('when you need a browser, check here first'), the when-not ('rather than calling writ_browser_use again'), and the follow-on action (pass session_id to writ_browser_act / writ_browser_context). The alternative path is fully 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?

Annotations declare destructive/openWorld/non-idempotent, and the description goes well beyond them: recording is always on, browsers bill until closed, the exit IP is fixed once open (so cancel and reopen with use_residential), and the tool is explicitly non-autonomous (the agent drives every step). This is unusually rich operational disclosure for a mutating, open-world 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?

Front-loaded with the core action and the key one-shot-per-task constraint, then organized under clear labels (RECORDING, WHAT YOU CAN DO, NOT FOR). It is very long, but nearly every clause carries operational information the agent must act on, so the length is mostly earned rather than padding.

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

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

With no output schema, the description carries the return burden and does so: it states it returns the FIRST live page observation and that the page comes back after every batch via writ_browser_context. It also covers the full task lifecycle (use -> act -> save/cancel) and the credential/2FA policy.

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 already 100%, giving a baseline of 3, but the description adds real meaning beyond it: persona_id ties a sealed credential and server-minted 2FA, execution_target explains the local_agent_offline recovery path, and use_residential is tied to the cancel-and-reopen bot-wall flow.

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 (opens a cloud browser) and its scope (real signed-in account, interactive site work) and explicitly contrasts itself against named siblings writ_scrape, writ_crawl_site and writ_website_to_api. An agent can tell exactly what this tool is and is not 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?

Contains an explicit NOT FOR block routing reading, listing and dataset collection to the correct alternatives, plus positive conditions (login wall, 403, CAPTCHA, form/click/submit). It also gives procedural gates: call writ_browser_sessions first, call this ONCE per task, and cancel to stop billing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral value beyond that: the download_url is short-TTL and fetchable with no further auth, and the returned field set is enumerated. It does not mention pagination beyond the schema's 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?

Two tight sentences, front-loaded with the resource and its differentiator, and no filler. The contrast with the DATASET is placed immediately after the identification, which is the right order.

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 burden of describing the return shape, and it does so (filename, size, version, source_url, download_url). Combined with 100% schema coverage for inputs and annotations covering safety, an agent has everything needed to call this 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 parameter baseline is 3. The description goes beyond that by clarifying the crawl_id-vs-crawl selection semantics ('for one run, or its most recent completed run(s)'), which the per-parameter schema text does not fully spell out.

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 resource ('the ORIGINAL documents a crawl captured') and enumerates the file types and returned fields, so the agent knows exactly what comes back. It also explicitly contrasts itself with the crawl's DATASET (extracted text), which is the nearest confusion point among siblings like writ_saved_crawl_data.

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

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

It states the selection condition clearly ('use this when you want the actual files') and names the alternative artifact (the DATASET with extracted text). It also explains the crawl_id vs. crawl routing choice. It stops short of naming a sibling tool by name or listing 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?

Annotations declare a write, non-idempotent, open-world, destructive operation, and the description adds substantial context beyond that: cost multipliers (AI executor 5x page rate), spend-capping via page_budget, wait/504 behavior, dataset persistence, login handling through persona_id, and re-run semantics for saved crawls. No contradiction with annotations.

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

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

The description is long but tightly organized with front-loaded caps headings (NOT FOR, CHOOSE THE MODE, SCOPE IT, DELIVERY) that let an agent navigate quickly. Given the tool's 35-parameter complexity the length is largely justified, though some expanded mode explanations 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?

For a complex tool with no output schema, the description explains the return envelope, data.rows behavior for bounded vs. open crawls, polling with writ_crawl_status, and how to reshape output for API consumers. This covers what an agent needs to call the tool correctly and interpret 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 35 parameters at ~77% schema coverage, the description adds decision-level meaning for the most consequential knobs: intent, rank_cap, seed_urls, extract_mode/executor interplay, output shape configuration, save_as, and content_spec. This meaning is not derivable from the schema descriptions alone and directly shapes correct invocation.

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 ('COLLECT A SITE ... INTO A DATASET') with clear scope, and explicitly contrasts itself against writ_scrape and writ_browser_use. An agent can identify this as the crawl-to-dataset tool without opening any schema.

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

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

It provides explicit when-to-use guidance (crawl <site>, build a dataset), when-not-to-use (one-off page reads, page actions), and names the alternatives (writ_scrape, writ_browser_use). It further routes between three execution modes and several scoping shapes with concrete conditions for each.

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 goes well beyond them: it discloses that wait=true becomes a single held call bounded at ≤75s, that rows are returned inline when it converges, and it explicitly forbids loop-polling. Latency ceiling and retry semantics are exactly the traits annotations cannot express.

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

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

Front-loaded with the core purpose, and the operational rule (never poll, use wait=true) lands early. Dense with em-dashes and parentheticals, and the phrase 'the answer to a crawl tool's 504 / crawl-id handle' takes a second read, but every clause carries information 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?

With no output schema, the description does the work of naming what a non-wait status call returns and what an inline `data` payload is shaped by. It stops short of describing pagination or the exact envelope for the plain status case, which is a minor gap for a 6-parameter tool with a nested 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 description coverage is 100%, and the nested `output` object is documented in exhaustive detail in the schema itself, so the baseline is 3. The description adds real meaning on top: it ties `wait` to a held call and `data` shaping, and frames the return fields (counts, status, workflow id) that the schema cannot. It does not touch `limit`, `preview_chars`, or `timeout_seconds`, which is why it stays at 4 rather than 5.

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

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

Names a specific verb+resource ('Status of a crawl by id') and enumerates what comes back (page counts, status, dataset workflow id). It also situates itself relative to the crawl-creating sibling by explaining it answers 'a crawl tool's 504 / crawl-id handle', so an agent can place it without opening the schema.

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

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

Explicit and prescriptive: use wait=true rather than polling, and if the crawl is still running at the ceiling, re-call once the same way. It also states the condition for setting `output` (when the answer is for a program rather than for the agent to read). No inference required.

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 annotations already declaring readOnlyHint=false, openWorldHint=true, and destructiveHint=false, the description adds rich behavioral context: webhook URLs are minted with a signing secret shown only once, calls are acknowledged immediately unless ?wait=true is used, and notification templates render empty on missing paths. These details go well beyond the safety profile provided by annotations.

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

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

The description is front-loaded with a clear purpose statement and organized into thematic paragraphs (notify, clock, webhook), which helps navigation. However, it is quite lengthy and uses dense all-caps emphasis, making it less concise than ideal, though most sentences carry useful, non-redundant 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?

Given the tool's complexity (25 parameters, nested objects, no output schema), the description is highly complete: it covers event triggers, action types, template syntax, webhook lifecycle, scheduling, and references to sibling tools. Annotations already cover the safety profile, so the description's depth fills all remaining gaps an agent would need to invoke 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?

Although schema description coverage is high (80%), the description adds substantial meaning beyond the schema, especially for notify templates (e.g., {{result.extracted_data.0.title}}, {{rows.0.<field>}}, {{extracted.price}}), webhook payload substitution ({{payload.<path>}}), and the blocks tree structure. It also clarifies parameter interactions like on_workflow being required for workflow_* events and run_functions calling selected workflow functions.

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 precise verb and resource: 'Create an automation: on an EVENT, run a workflow, send a notification, and/or wake an AI agent.' It clearly distinguishes the tool from siblings by naming related tools (writ_set_schedule, writ_list_webhooks) and explaining the unique combination of event triggers, actions, and scheduling.

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

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

The description explicitly covers when to use each trigger mode (workflow_completed, scheduled, webhook_received) and provides concrete patterns like 'THE DIGEST PATTERN' that route the agent to specific sibling tools for complementary tasks. It also specifies required combinations ('at least one of run_workflow / notify / ai_prompt') and references alternatives such as writ_set_schedule and writ_list_webhooks.

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, the description discloses the draft-versus-write behavior of apply, the generated artifact as universal api_call.config.flow, and the operational requirement to run and prove engine=http with writ_diagnose_http_workflow before exposing the workflow. It also adds safety constraints such as never putting fetch in evaluate_js and never sending Writ-only controls to the site. These details materially help an agent avoid destructive or invalid actions.

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 dense and front-loads purpose, usage conditions, workflow steps, and safety constraints. Although long for a tool definition, each sentence carries routing, behavioral, or validation guidance rather than filler. Minor density in the middle section keeps it from a perfect score.

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 mutation tool with rich annotations but no output schema, the description covers the full lifecycle: preconditions, draft review, apply behavior, post-apply workflow execution, and diagnostic proof. It does not need to explain return values because no output schema exists, and the annotations already cover open-world and destructive traits. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 89%, so the input schema already carries most parameter meaning, including apply, goal, workflow, step_index, request_samples, and desired_inputs. The description adds sequencing for apply but does not meaningfully extend the semantics of the remaining parameters beyond what the schema provides. Thus 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?

The description states a specific verb and resource: create or revise an advanced browserless HTTP extraction from plain language and browser-network evidence. It clearly distinguishes this from siblings such as writ_browser_compose for ordinary login/bootstrap chains and writ_diagnose_http_workflow for post-apply validation. An agent can identify the tool's scope 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?

It gives explicit when-to-use guidance: use AFTER a browser experiment/capture_network when simple requests or Auphan-style auth/function graphs are insufficient, and lists concrete triggers like request loops, GraphQL discovery, recursive JSON, dedupe, sorting, and cursor pagination. It also routes ordinary chains to writ_browser_compose and prescribes apply=false first, then apply=true, followed by workflow proof.

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, destructiveHint=false, openWorldHint=true, but the description goes well beyond: it explains the needs_input flow when interval is omitted, the needs_persona path for sign-in pages, the bot-check offer of use_residential, the refusal/warning outcomes for disallowed intervals, and the `selector_check` field returned. This is deep behavioral disclosure for a mutating, open-world 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?

Front-loads purpose, then the selector-proof procedure, then frequency/account behavior; every section maps to a real prerequisite for a 17-parameter tool. It is dense and caps-heavy, and some interval semantics restate the schema, so it is efficient but not spartan.

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 17-parameter, open-world, non-idempotent creation tool with no output schema, the description covers the full lifecycle an agent needs: prerequisite session, selector validation, browserless alternative, scheduling/needs_input, auth/bot-wall handling, and the returned monitor id. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the per-parameter text already carries most semantics (baseline 3). The description adds cross-parameter workflow meaning the schema cannot convey: session_id must be supplied before saving, selector matching several elements gets pinned, mode='visual' requires session_id/zone_text, and extract/request_url may replace selector/requires_browser.

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+resource ('Create a MONITOR') and immediately defines the resource's scope: a scheduled target that fires a change_detected event on content, selector-text, or visual-zone change. It also names the sibling it hands off to (writ_wire_monitor) for alerting, so the agent can distinguish it from the rest of the browser/workflow 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?

States explicitly when to use it ('when the user wants to WATCH a URL for changes/updates'), and routes specific situations to alternatives: writ_browser_use to prove the selector, extract over selector when the value is readable without JS, mode='visual' when no selector matches at all. The when-not guidance (extract preferred for browserless, no interval → needs_input) is unusually complete.

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?

Adds real behavioral context beyond the annotations: which downstream tools get re-scoped, that run history/data/monitors are read from and created on the chosen desktop, and that persona credentials never leave the desktop's vault. The annotations already cover the safety profile (idempotent, non-destructive), so a 4 reflects solid added value without full return-format disclosure.

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 resource and the default, then the actions in order. Sentences are dense but each carries a distinct consequence; slightly long parenthetical tool lists, though none are pure 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, so the description does the work of describing what list returns (connection status, workflow/persona counts), which it handles. The one gap is that the 'datasets' action appears in the enum but is never addressed in the description.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the downstream effect of each action (use scopes runs/browser/workflows/personas; clear removes scope) and that device accepts an agent_id or exact name from list. Only action='datasets' is left unexplained 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?

States a specific verb+resource (list linked WRIT desktops, or scope the connection to one) with a clear scope distinction. The tool is instantly separable from siblings like writ_list_workflows or writ_browser_use because it is explicitly the connector they route through.

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 when to use it: 'on my laptop', 'on my work computer', or when the user wants their own browser and logins. It also states the default action and the clear action, so when-not is covered by the list/use/clear triad.

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 the description adds substantial behavior beyond that: it discloses what the report contains, how task_id changes the output (run steps plus every request's status, sizes, and a response sample), and how to interpret a 200 with an empty feed versus genuinely 'no matches'. That interpretation guidance is real diagnostic value not present in 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 purpose, then usage, then diagnostic interpretation, so the ordering is sound and little is filler. The second sentence is very long and packs several ideas together, which costs some scannability, but the density is largely substantive rather than 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?

With no output schema, the description must explain returns and it does so thoroughly, including what a successful proof looks like and what the task_id run payload contains. The remaining gap is the unresolved workflow/workflow_id parameter pair, which an agent still has to guess about.

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 33% (task_id is the sole documented parameter), so the description carries extra burden. It explains task_id well, including what its presence changes, but says nothing to disambiguate 'workflow' (string) from 'workflow_id' (integer), leaving the weaker two-thirds of the surface unresolved.

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 with scope: 'Diagnose HTTP-lane readiness for a saved workflow.' It then enumerates exactly what it reports (browser-only dependencies, invalid actions/expressions, unsafe query params, proof vs eligibility, next repair action), which distinguishes it from siblings like writ_workflow_runs or writ_run_workflow 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 clear conditional usage: pass task_id after a representative run to confirm engine=http, no fallback, and RECORDS returned, and says to read the returned step/request answer data FIRST when a run returned nothing or failed. It does not name an alternative tool or state when not to use this one, so it stops short of explicit routing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context: terminal states, the needs_guidance 'resting' state and its ownership semantics, superseded/fallback_build_id pointer following, escalations as historical hand-off reasons, and the meaning of verified=false. This is far beyond what the annotations 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-loaded with purpose and terminal states, and nearly every sentence carries operating information. It is dense and some sentences are long, but there is little filler given the amount of behavior being disclosed.

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 describe returns, and it does: workflow_id, mapped surfaces, verified flag, escalations, map contents, and followed_from. An agent has everything needed to call it and interpret the response.

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 real meaning on top: it explains the wait=true continuation contract ('call again with wait=true and the build_id this answer carries') and the follow-pointer behavior, which the schema's terse wait description only gestures at.

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+resource ('Poll a build started by writ_website_to_api') and names the sibling that creates the build. An agent can immediately tell this is the status/polling counterpart to writ_website_to_api.

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

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

Explicitly states when to poll vs. use wait=true, what to do in the needs_guidance state, how to continue a build, and routes downstream actions to writ_run_workflow and the api-docs endpoint. It names alternatives and the conditions that select them.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description usefully adds that the export is un-paginated and returns the FULL table, which warns the agent about potentially large payloads, but it says nothing about auth requirements, size limits, or whether filters must be set to avoid huge results.

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 front-loaded sentence with no filler; the key behavioral fact (un-paginated, filter-applied full table) is surfaced immediately.

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 five mostly-undescribed parameters, no output schema, and no indication of which identifiers are required, the description leaves an agent guessing how to target the right workflow and what the returned payload looks like. Given the low schema coverage, it needed to compensate more than it does.

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 20% — just 'format' is documented, and the description only restates csv/json. The meaning of q, view, workflow and workflow_id (and which of the redundant workflow/workflow_id to use) is left entirely undocumented despite 5 parameters and zero required fields.

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

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

States a specific verb (Export) and resource (a workflow's full extracted-data table) plus the output formats, so an agent knows exactly what it produces. It doesn't explicitly distinguish itself from close siblings like writ_workflow_data or writ_search_data, which is the only reason it isn't a 5.

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

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

'search/filter applied, un-paginated' implies this is the bulk-export counterpart to a paginated/search tool, but no alternative is named and no when-to-use or when-not-to-use condition is given. Usage must be inferred from the parenthetical.

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 safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real context: the returned POST URL blocks until the workflow finishes and returns its JSON result, and repeat calls are idempotent (reuse the endpoint). It does not mention auth/permission requirements, which is the remaining gap.

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

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

Three tight sentences, front-loaded with the core action, then the return behavior, then the idempotency note. 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 appropriately explains the return (a POST URL that returns the workflow's JSON result) and the idempotency behavior. It is complete for invoking, though it omits permission/prerequisite context and gives no parameter guidance.

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?

Five parameters with only 60% schema coverage; 'workflow' and 'workflow_id' have no description in either schema or description text, and the description adds nothing about how to specify which workflow, the label, or timeout behavior. It does not compensate for the 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+resource: publishing a saved workflow as a managed REST endpoint, and clarifies it uses the same resource as the frontend's REST switch. It is distinguishable from siblings like writ_run_workflow or writ_website_to_api, though it never names an alternative 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 context is implied (expose a saved workflow as an API endpoint) and it notes that repeated calls reuse the existing endpoint, but there is no explicit when-to-use/when-not guidance or comparison against alternatives such as running the workflow directly.

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, so the safety profile is covered. The description adds value beyond them: signing secrets are stored encrypted and never returned, and it clarifies that reuse vs. minting of webhook URLs depends on supplying webhook_trigger_id.

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

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

Three sentences, front-loaded with the resource and its returned fields, then the security caveat, then the integration rule. No filler or repetition; every clause carries 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?

With no output schema, the description usefully enumerates the returned fields and the security constraint, and annotations cover the safety profile. What is missing is minor: no guidance on empty results, pagination, or ordering of the listed URLs.

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

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

Schema coverage is 100% and the single optional webhook_trigger_id is documented in the schema as 'Only this webhook.' The description adds no filter syntax or behavior beyond that, so the baseline 3 for a fully documented parameter set 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: it lists the account's inbound webhook URLs and enumerates exactly what is returned for each (webhook_trigger_id, callable url, signed status, firing automations, call count). An agent immediately knows this is a read of webhook configuration, not a crawler, workflow, or browser tool like its 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?

It explains the relationship to writ_create_automation (reuse an existing webhook_trigger_id; when='webhook_received' without it mints a new URL), which supplies real context for the trigger id. However it never states when to call this listing tool rather than alternatives, nor any exclusion or precondition for the optional filter.

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 and destructiveHint=false, so the safety profile is covered. The description still adds genuinely useful behavior: each workflow "runs on demand without live browsing" and the response enumerates id, name, declared inputs, schedule, and pinned-tool status.

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

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

Two tightly written clauses: purpose/scope first, then the return contract. No filler, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description usefully enumerates the returned fields and the execution model (on-demand, no live browsing), which an agent needs to decide follow-up actions. It omits only routing guidance to alternative list tools.

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

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

Schema description coverage is 100% for the single optional `search` parameter, so the schema already carries the semantics. The description adds nothing about the filter, 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+resource ("List the workflows saved in your Writ account") and clarifies the scope relative to live-browsing siblings. It does not name a specific alternative sibling (e.g. writ_workflow_runs vs writ_list_workflows), so differentiation is contextual rather than explicit.

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 tool lists saved workflows, so an agent can infer this is the discovery step before running or pinning one. There is no explicit when-to-use, when-not-to-use, or named alternative, leaving the agent to infer routing against siblings like writ_workflow_runs and writ_saved_crawls.

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 (destructiveHint=true, openWorldHint=true), the description discloses critical behavior: card numbers never reach the conversation, card use is scoped to site and amount granted, grants expire after 15 minutes, wait is a single held call up to 60s, and checkout pauses for user confirmation before Writ places a real purchase. This is unusually rich context that annotations cannot 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?

The opening clause front-loads the key constraint (no card numbers) and the request flow, and every sentence carries substantive information. It is dense and long, but for a 15-parameter, five-action tool this density is largely earned; slightly tighter per-action grouping would improve scanning.

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 mutation tool with 15 parameters, nested objects, and no output schema, the description covers the entire workflow from approval to order placement and explains the return shape (brand and last four digits, confirmation outcome). 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics: which action consumes grant_id versus confirmation_id, that checkout without grant_id requires max_amount, and how commit_selector/total_selector gate the auto-confirm rule. It enriches schema-level info rather than merely repeating it.

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 (pay on a website using the user's cards) and enumerates all five actions with their distinct functions. It clearly differentiates from siblings by routing card handles into writ_wire_monitor and by referencing writ_browser_context for selector reading.

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?

Each action's use case is stated explicitly: request to obtain approval, wait to hold for a grant/confirmation, checkout to place the order, fill for multi-page checkouts, list to enumerate payment methods. It also names alternatives (writ_wire_monitor for buy.payment, writ_browser_context for reading selectors) and an exclusion ('You never click an order button yourself (refused)').

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 annotations: no password passes through the tool or conversation, credentials are sealed server-side and never readable, 2FA codes are minted server-side, sessions are warmed, wait holds up to 75s and answers on save/decline/close, and desktop personas sign in from their own vault only on their own site. This is rich operational context that annotations (openWorld, not read-only) 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?

The content is valuable and the action-routing is front-loaded, but it is a dense wall of run-on, heavily-bolded sentences that mix definitions, workflows, and return shapes. Some of the length is justified by six actions, yet it is harder to parse than it needs to 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 9-parameter, six-action tool with no output schema, the description does the heavy lifting by describing return keys (persona_id, link_id, still_waiting, persona_needed with tell_user/create_url). It is nearly complete, though the response shapes could be stated slightly more cleanly.

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: the request→link_id→wait→persona_id workflow, that domain does suffix matching and yields persona_needed, and that link_id answers with persona_id/still_waiting. This meaningfully enriches how the parameters relate.

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 defines the resource precisely (a 'saved sign-in identity' with sealed credentials) and enumerates the concrete actions (list, get, sign_in, record_login, request, wait). It also distinguishes itself from siblings by naming the tools it feeds (writ_browser_use, writ_crawl_site, writ_scrape, writ_run_workflow), so an agent can tell what it is and how it connects to the ecosystem.

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: use persona_id in the sibling tools, call action='list' (filtered by domain) BEFORE asking the user for credentials, use 'sign_in' to run the login now, 'record_login' to capture a workflow, and 'request'/'wait' to mint and hold for a new persona. It even states what the tool cannot do ('can NOT create a persona') and warns against polling loops.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description's job is to add context. It does: workflows are never exposed by default, unpinning reverses the effect, and the derived tool list is capped. Return-shape detail is absent, but that is minor here.

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

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

Three sentences, front-loaded with the action and effect, then the constraint, then the trigger condition. Slightly dense with parentheticals, but every clause carries routing or constraint 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?

With no output schema and full annotation coverage, the description supplies the missing piece — why and when this tool exists relative to writ_run_workflow. Only the workflow vs workflow_id choice and any cap/pagination behavior remain unstated.

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% and the description mirrors rather than extends it, restating the pin/unpin toggle and naming the workflow as the target. It adds no disambiguation between workflow and workflow_id, and the undocumented workflow_id param is left untouched.

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 precise verb pair (pin/unpin) plus the concrete resource and effect: creating a derived run_<name> tool on this server. It explicitly contrasts itself with writ_run_workflow, so an agent can distinguish it from the default invocation path.

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 ('when the user asks for it, or after saving a workflow the user clearly intends to call as a tool') and an implicit when-not ('pin only the few… the derived list is capped') plus the named alternative writ_run_workflow for non-pinned use.

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?

Adds substantial context beyond the annotations: it opens a real cloud browser and returns an observation, the agent must drive it via writ_browser_act/compose/save, the saved workflow replays at zero AI cost and can be scheduled, and it proposes existing_workflows/marketplace_candidates before running. It does not explain the destructiveHint=true implications or permission/auth needs, which keeps it short of a 5 against already-rich annotations.

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

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

Front-loads purpose in sentence one and each following sentence carries routing or workflow information. It is dense and long with heavy parenthetical content referencing many sibling tools, which costs some readability, but little of it is padding.

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

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

For a complex 8-parameter, open-world, non-idempotent recording tool with no output schema, the description covers the trigger, the alternatives, the multi-tool authoring flow and the bypass flags. It stops short of describing the return/observation shape or failure behavior, but is complete enough to 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 the schema already documents all 8 parameters, making 3 the baseline. The description adds only marginal meaning (the skip_existing/skip_marketplace bypass rationale) and no extra syntax or format detail 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?

Opens with a specific verb+resource: 'Record a repeatable website TASK as a workflow that replays on demand.' It explicitly distinguishes this tool from the sibling writ_website_to_api by stating API-shaped goals are routed there automatically, so an agent can tell them apart 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 trigger ('whenever the user asks to record, capture, teach, automate or repeat actions on a site and the point is the TASK'), names the alternative and the condition that selects it (API goals -> writ_website_to_api), and sketches the in-tool flow (act/compose/save) plus skip_existing/skip_marketplace bypass semantics.

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

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

Annotations declare non-readOnly, non-idempotent, open-world, and the description adds genuinely new behavioral context on top: the cache-vs-recrawl decision, the cheap path, and the `_cache.hit` / `_cache.age_seconds` response fields. It still doesn't note that a run may be slow or that repeated calls without max_age duplicate work, but the added caching semantics are substantive.

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, zero filler, front-loaded with purpose followed by the caching decision and the means to verify it. 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?

With no output schema, the description discloses the most decision-relevant return fields (`_cache.hit`/`age_seconds`) and the caching model, which is enough to call it correctly across 7 params with full schema coverage. It stops short of describing the general response envelope or the non-idempotent side effects of an actual re-crawl.

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

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

Schema coverage is 100%, so baseline is 3, and the description goes beyond the schema by framing max_age as the 'cheap path' shortcut and by documenting the `_cache` response fields that appear in no parameter description. The wait/timeout/output parameters are left entirely to 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 (run) and resource (a saved crawl) and immediately scopes it with 'with its stored settings', which distinguishes it from writ_crawl_site (new crawl) and writ_update_saved_crawl (mutation of the definition). An agent can pick it out from the sibling list without opening any schema.

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

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

It gives one useful conditional: pass max_age for the cheap cached path, otherwise it re-crawls. But it never says when to choose this tool over writ_crawl_site, writ_scrape, or writ_saved_crawl_data, nor does it state prerequisites for the saved crawl existing. 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation profile is partly covered. The description adds the default synchronous wait-and-return-extracted-data behavior, but never mentions the live-write default or the dry_run/private_test escape hatch (that lives only in the schema), leaving key behavioral context on the param descriptions.

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, front-loaded with the core action and the default behavior; no filler or repetition.

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

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

For a 16-parameter, nested, open-world execution tool with no output schema, the description is thin: it omits mention of function_name/function_names selection, mutation_mode, execution_target, persona/device routing, and max_age caching. The schema covers these well, but the description does little to orient an agent on 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 description coverage is 100%, so the baseline is 3. The description does add the convention that inputs may be passed as top-level fields or under `inputs` and file inputs under `files`, but much of this is also restated in the schema, so marginal added value.

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 ('Run a saved workflow') and adds useful scope: identified by id or name, defaults to waiting for completion and returning extracted data. It does not name or distinguish itself from siblings like writ_workflow_runs or writ_website_to_api, so it stops short of a 5.

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

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

The description implies usage through the default-wait behavior and input-passing conventions, but gives no explicit when-to-use/when-not guidance versus the many sibling run/inspect tools (writ_workflow_runs, writ_replay, etc.).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavior beyond that: the data is a cached snapshot of the most recent completed run only, and calling it never triggers a crawl — an important expectation-setting detail.

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, with the read-only, no-run-started constraint front-loaded before the usage hint. Nothing is repeated from the title or 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, the description usefully states which run's data is returned and that it is never mutated, which compensates for the missing return-value documentation. Pagination and response-shape behavior are left entirely to the schema, which documents the output param but no return format.

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 nested output object, limit, and preview_chars are all documented in the schema with defaults and semantics. The description adds no parameter-level guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read the data a saved crawl already collected') and pins the exact data set ('most recent completed run'). The phrase 'Never starts a crawl' cleanly separates it from writ_run_saved_crawl and writ_crawl_site without needing to open 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?

'use this when you want what is already there, at any age' gives a clear condition for selection, and the negative clause rules out triggering a fresh run. It stops short of naming the alternative tool (writ_run_saved_crawl) for the fresh-run case, leaving that inference to the agent.

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 and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the API-callable nature of saved crawls, the per-item `scope` structure, and the behavioral caveat that executor=ai crawls are not reusable for fresh questions. It does not discuss result ordering 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?

Three sentences, front-loaded with the purpose before the routing advice, and each sentence carries information. It is dense with parenthetical detail, but nothing is filler or restated boilerplate.

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 compensates by describing the shape of each returned crawl and its scope fields, plus the correct follow-up tool. The only gaps are result count/ordering and whether limit truncates silently, which are minor for a read-only list 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?

There is a single parameter (limit) at 100% schema description coverage, so the schema already carries the semantics; the description never mentions limit and adds nothing parameter-level. Baseline 3 is appropriate when the schema does the heavy lifting.

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 the crawls the user SAVED for re-running') and immediately characterizes what a saved crawl contains (scope with seed_url, rank_cap, include_paths, extract_mode, executor). It is unambiguously distinguishable from sibling write tools like writ_update_saved_crawl or writ_run_saved_crawl.

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

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

Explicitly routes between alternatives: use writ_run_saved_crawl(max_age=…) when the scope matches, otherwise start writ_crawl_site(rank_cap=N). It even names the exclusion case (different page, or executor=ai) that disqualifies a saved crawl as a shortcut, which is unusually precise 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?

Discloses behavior well beyond the annotations: 2-10s latency, parallel fetching, 12000-char preview cut with a `_truncated` flag, a `hint` for full retrieval, 'YOU read the markdown — no AI is spent here', and the escalation paths for bot walls (use_residential) and logins (persona_id). Nothing here contradicts readOnlyHint=false/openWorldHint=true; a network egress that may consume premium residential is consistent with non-read-only.

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 and sectioned ('THREE SHAPES, ONE CALL EACH'), so an agent can scan the operative rules quickly. It is nonetheless long and stylistically dense (all-caps opener, heavy em-dash nesting), so a little more restraint would help; every section still carries non-redundant 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?

With no output schema and 12 parameters, the description carries the return-shape burden itself, naming `pages`, `listing`, `_truncated`, `hint`, and the comment depth tags, plus failure modes (403/bot wall/JS/empty) and their remedies. Nothing an agent needs to call or interpret this tool 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?

Although schema coverage is 100%, the description adds combinatorial meaning the schema cannot express: the three argument shapes (single url, urls≤20, url+top_n≤20) and exactly what each returns (`pages` in given order, `listing` + ranked `pages`, comment depth tagging). It also clarifies defaults and cross-tool differences for respect_robots, include_paths auto-detection, and residential_country.

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 PAGE CONTENT') and differentiates immediately from siblings: 'NOT FOR: collecting a whole site ... (writ_crawl_site); clicking, typing, signing in ... (writ_browser_use)'. An agent can pick this tool without opening a sibling 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 phrasing mapped to user intents ('what does <page> say', 'summarize <url>', 'top N posts') plus a dedicated NOT FOR section naming the two alternative tools and their domains. Exclusions and alternatives are both covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: it discloses the fan-out-across-workflows behavior and that matches return preview-sized (truncated) rather than full records, which is important for interpreting results. It does not state rate limits or result-count caps beyond the per-workflow 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?

Three compact sentences: purpose and scope first, scoping behavior second, and the follow-up retrieval path last. Every sentence carries information and none repeats the name or 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, the description appropriately covers what results look like (preview-sized matches) and how to get complete records. For a read-only search with 6 params, the remaining gap is the untold interaction between the workflow and workflow_id params and any result caps.

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

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

Schema description coverage is 67%, so the schema already documents q, limit, device, and preview_chars. The description adds conceptual meaning for preview truncation and for workflow scoping, but does not explain how workflow vs workflow_id interact or what default preview size it uses. This is adequate-but-marginal value on top of 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 (search) and resource (data collected by workflows), and clarifies the scope ('everything already collected') versus running something new. It explicitly distinguishes itself from the sibling writ_workflow_data, which is used to fetch full records, 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?

Clearly frames the use case ('answers data questions from past runs without running anything') and names the follow-up tool with the exact trigger ('fetch full records with writ_workflow_data'). It also explains scoping ('Scopes to one workflow when given, else fans out'). It lacks explicit when-not-to-use guidance versus other data siblings like writ_saved_crawl_data or writ_export_data.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds behavioral context beyond that: each run executes targeted functions plus dependencies exactly once, and the response names also_runs and missing_inputs. No contradiction with annotations.

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

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

Front-loaded with the core purpose, then parameter modes, then advanced multi-function behavior, then response details. It is dense but each sentence earns its place. Slightly complex phrasing in the third sentence, but overall efficient.

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 11 parameters, nested objects, no output schema, and annotations that already cover safety, the description provides enough context to invoke the tool correctly. It explains scheduling modes, function targeting, dependency resolution, and response hints. Minor details like tz defaults and workflow vs workflow_id selection are left to the schema, which is reasonable at 82% coverage.

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 high at 82%, so the baseline is 3. The description adds semantic meaning beyond the schema by clarifying the interplay between functions, inputs, and whole-workflow targeting on multi-function APIs, and by explaining the dependency execution model. It does not fully cover every parameter, but it meaningfully supplements 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 ('Schedule') and resource ('a saved workflow') with automatic recurrence, distinguishing it from writ_run_workflow (manual run) and writ_update_workflow (modify). The added multi-function targeting explanation further narrows its scope. An agent can identify the tool's purpose 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?

Provides mode selection guidance ('Use every_minutes for an interval, or kind="daily"/"weekly" with time and days'), which is parameter-level usage. However, it never explicitly says when to choose this tool over alternatives like writ_run_workflow, writ_create_automation, or writ_update_workflow. Usage is implied rather than fully contextualized.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds genuinely useful context beyond them: the settings patch is a recursive merge that preserves unrelated settings, which materially softens how an agent should interpret the destructive hint. It omits auth requirements and whether the merge can be reverted.

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

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

Two sentences, front-loaded with purpose, then the non-obvious merge semantics. No filler or repetition of the title.

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

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

For a mutation tool with annotations covering safety and no output schema, the description explains the read-vs-edit behavior and merge semantics adequately. It could say more about whether changes require a separate apply/save step or what happens on invalid patch keys.

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 40%, but the description compensates for the most complex parameter by explaining that `settings` is a sparse recursive patch over the full stored config. `name`, `description`, and `default_max_age_seconds` are self-evident and need no further 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?

States a specific verb ('inspect or customize') and resource ('a saved crawl') and the in-place nature, distinguishing it from writ_saved_crawls (listing) and writ_run_saved_crawl (executing). It is clear but does not explicitly name a sibling to contrast against.

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 dual behavior is implied ('With no changes, returns its complete definition' vs. merging changes), which tells an agent it can be used as a read. However, there is no explicit when-to-use guidance, prerequisites, or named alternatives among the many sibling tools.

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 mark destructiveHint=true and readOnlyHint=false, so the description correctly implies mutation and the ability to replace steps. The description adds critical context: 'replace_steps deliberately replaces the complete step list', and details on patch fields and skill regeneration. It doesn't elaborate on permissions or side effects like data loss, but with annotations covering the safety profile, this 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?

The description is dense and front-loads the core purpose, but it is quite long and includes detailed technical examples (api_call structure) that could be moved to a separate section. Some sentences are lengthy and could be split for clarity, but overall it is informative without excessive fluff.

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

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

Given the tool's complexity (7 parameters, nested objects, many patch fields), the description covers key behaviors: read vs edit, verbose mode, step_updates vs replace_steps, skill regeneration, and patch scope. It lacks explicit prerequisites (e.g., authentication needs) and error handling, but with no output schema and schema at 71%, it is largely complete for an agent to call 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 71%, so there is some gap. The description adds meaning beyond schema: it explains that patch changes settings including a long list of specific fields; that step_updates recursively edits steps with examples (selectors, scripts, URLs, waits, flags, extraction config); and clarifies the api_call step structure with config fields. This compensates for the schema gap effectively, though not exhaustively.

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 ('Inspect or completely customize') and resource ('existing saved workflow in place'), and differentiates itself from siblings by naming writ_run_workflow function_name binding. An agent can tell this is the edit tool, distinct from writ_list_workflows or writ_run_workflow.

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

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

Provides clear context: 'With no edit arguments, returns the full workflow', 'Prefer step_updates for a targeted edit', and explains replace_steps vs step_updates. However, it doesn't explicitly state when-not-to-use (e.g., for creation, use a different tool) or list alternatives beyond replace_steps.

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 adds extensive behavioral context beyond annotations, such as the cost ladder, escalations, robots handling, verification status, persona login, and parked builds. However, it states that level=deep performs real create/update/delete writes and 'CHANGES real data,' while the annotations declare destructiveHint=false. That is a direct annotation contradiction, so per the rubric this dimension scores 1.

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 opening is front-loaded and identifies the core job quickly, but the description becomes an all-caps wall of text that repeats mode and parameter details already covered by the schema. For a tool whose parameter documentation is already complete, this level of redundancy and density is not 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 complex 17-parameter orchestration tool with no output schema, the description covers selection, the full call flow, modes, authentication, robots restrictions, verification caveats, and follow-up tools. Despite the verbosity, an agent has enough context to start, continue, and recover a build.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters, making 3 the baseline. The description adds useful cross-parameter context—build_id continues a parked build, persona_id handles sign-in/2FA, respect_robots ties to escalations—but much of the mode and level explanation duplicates 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+resource: turning a website into a callable API. It explicitly distinguishes itself from sibling tools by naming writ_scrape, writ_crawl_site, and writ_record_website as NOT FOR cases. An agent can identify the tool's core job without opening the schema.

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

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

Gives explicit when-to-use guidance, the intended three-call workflow, the follow-up status/run/diagnose tools, and clear exclusions. It also explains which mode to choose and when to escalate, leaving little 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 only declare the safety profile (readOnly=false, destructive=false, openWorld=true); the description goes well beyond, disclosing that auto-buy is always saved as a dry-run rehearsal until armed in the app, that price thresholds fire once and require a selector/extract, and that ai_task wakes an autonomous agent. These are material behavioral facts not available in annotations or schema.

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

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

Front-loaded with the core purpose, then mode behaviors, price watch, and auto-buy in a logical order with UPPERCASE emphasis on the riskiest mode. Dense but every clause is load-bearing; slightly long for a single description but not 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?

For a 19-parameter, nested-object tool with no output schema, the description covers the routing logic across action modes, the price-watch constraint, and the auto-buy safety model, which is what an agent needs to invoke it correctly. Nothing critical is left 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?

With 84% schema coverage the baseline is 3, but the description adds real semantics: how action modes partition which params apply (channels/recipients for notify, prompt/workflow for others), the threshold single-fire semantics tied to threshold_op, and the buy/spend_cap defaulting behavior. This meaningfully exceeds the schema text.

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

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

States a specific verb+resource ('Wire a monitor's change_detected event to an action') and immediately enumerates the three concrete action modes with their distinct behaviors. It is clearly distinguished from writ_create_monitor, which is named as the prerequisite sibling.

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

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

Explicitly says 'Use after writ_create_monitor to make the monitor DO something on change,' and gives per-mode usage conditions (workflow vs notify vs ai_task), plus the price-watch single-fire rule and the auto-buy rehearsal rule. Alternatives and exclusions are stated, not inferred.

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 the description adds non-obvious behavior beyond them: text cells arrive preview-cut, `_truncated` lists the cut fields, and full records are hydrated via refs. It omits pagination/limit defaults and what `view` modes do, but the truncation-and-hydration disclosure is genuinely additive.

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 filtering, then truncation/hydration behavior, closing with the namespace caveat. Every sentence carries load-bearing information and there is no restating of the title or 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?

For a 10-param tool with no output schema and a nested output object, the description covers the essential read path, truncation semantics, and cross-namespace disambiguation well. Gaps remain around the view/limit/device parameters and the saved-workflow concept, but nothing blocks a correct call.

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

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

Schema coverage is 60%, and the description meaningfully explains q, run_id and the refs hydration path (equivalent to '<run_id>:<record_index>'). However several parameters (view, limit, device, workflow/workflow_id) get no clarification beyond the schema, so it only partially compensates for the 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 ('Read the accumulated extracted data for a saved WORKFLOW as a table') and describes the output shape (columns + rows). The NOTE explicitly differentiates this from the crawl-data siblings (writ_crawl_status / writ_saved_crawl_data), 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 concrete routing guidance: 'Filter with `q`, or inspect one run with `run_id`', and the NOTE names the alternatives to use for crawl data with the condition that selects them. It stops short of contrasting with other plausible siblings like writ_search_data or writ_export_data.

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, and destructiveHint=false, so the safety profile is clear. The description adds that it surfaces status, timing, and errors, which is useful context beyond the annotations. However, it doesn't disclose pagination, default limits, or ordering, which are relevant for a list endpoint.

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?

Single sentence, front-loaded with the action and resource, with a clear scope clause. Efficient, though it could be more informative without waste.

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

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

Given 5 parameters, no output schema, and moderate annotation richness, the description is minimally adequate. It tells what the tool returns conceptually but doesn't cover parameter usage or behavioral details like pagination, which an agent needs to invoke correctly. It's not misleading, but it leaves gaps.

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

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

Schema coverage is 40%, so the description should compensate but does not: it mentions status, timing, and errors but not the parameters limit, device, status, workflow, or workflow_id. The schema itself provides descriptions for device and status, leaving limit, workflow, and workflow_id undocumented in both schema and description. Baseline 3 when schema partially covers; here it's slightly below because description adds almost no parameter meaning.

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?

Clearly states the verb and resource: inspecting run history for workflows. It specifies scope ('one workflow or across all of them') and names the returned attributes (status, timing, errors). It doesn't explicitly differentiate from siblings like writ_list_workflows or writ_workflow_data, but the resource (runs vs workflows vs data) is distinct enough.

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?

No guidance on when to use this vs alternatives. The sibling writ_list_workflows lists workflows and writ_workflow_data retrieves workflow data; it's unclear when an agent should call this tool instead. The description implies it's for inspecting run history but doesn't mention exclusions or companions.

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