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

With no annotations, the description carries full burden. It discloses the return shape ({path, title, shape, hash}), explains hash covers body only, and describes the provenance front-matter. This meaningfully discloses behavioral traits beyond what a schema would show. It could mention whether it overwrites or creates new files, and the 'timestamped' wording implies immutable append-style behavior.

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

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

Two tight paragraphs, no filler. First paragraph states the action and target; second explains return value and hash semantics. Every sentence earns its place with concrete operational detail.

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 write-style tool with 2 params and no annotations, this is reasonably complete: storage target, return shape, and hash semantics are all covered. The 'private' parameter remains a gap, and interaction with watch_diff/watch_scan siblings isn't addressed, but the core behavior is well-documented.

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

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

Schema coverage is 0%, so the description must compensate. The description explains url (page to fetch) indirectly, and 'private' is never mentioned. However, with only 2 params and one being self-evident (url), the coverage gap is modest. The description adds value about storage location and return semantics but leaves 'private' semantically unexplained.

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

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

Very specific: 'Fetch a page and save a timestamped markdown archive with provenance front-matter.' Verb+resource+output format are all clear. It distinguishes from siblings (archive_search, fetch_archived) by describing the archiving action and the storage target.

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 explains that it saves to app-data archive or $MDBROWSE_ARCHIVE, giving context on where results land. It explains how to detect content changes via hash comparison, which functions as a when/WOW-to-use pattern for repeated archiving. However, it doesn't explicitly state when to prefer this over fetch_archived or fetch_page, nor 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?

With no annotations provided, the description carries the full burden. It reveals return shape, result ordering (best-first), the Term-AND matching semantics, and how to access full content. It's a read-only search so no destructive concerns, but it doesn't mention pagination limits or whether it's read-only explicitly. Solid disclosure for a search tool.

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

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

Two compact sentences with zero waste. Front-loaded with the core purpose, then return format and follow-up guidance. Every clause earns its place.

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

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

For a read-only search tool with a documented return shape and follow-up guidance, this is quite complete. Lacking output schema is fine since the description documents the return fields. Minor gaps: query syntax details and max_results semantics, but these are low-stakes for a search tool. Complex enough (2 params) that the description adequately covers.

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

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

Schema coverage is 0%, so the description must compensate. It explains what 'query' does implicitly (Term-AND full text matching) but doesn't describe the query syntax, how max_results interacts with results, or format expectations. max_results is self-evident from its name. The description adds moderate value but leaves query syntax unspecified.

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?

Clear verb+resource: 'Search previously archived pages'. It specifies the source (personal web memory archive_page writes to), the search mode (Term-AND full text), and the return format ({path, title, source, retrieved, score, snippet}). The reference to archive_page distinguishes it from general web search.

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

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

Explicitly distinguishes from siblings by noting it searches the archive written by archive_page, which separates it from search_web and fetch_archived. It also instructs to 'Read a hit's path for the full page as it was when archived,' offering a follow-up action. However, it doesn't explicitly say when NOT to use it or name alternative tools as the top-tier examples do.

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

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

No annotations are provided, so the description carries the burden. It describes the output (markdown with provenance front-matter: source URL, retrieval time, content hash) and mentions default config paths ($MDBROWSE_CORPUS_ROOT, /mnt/herfjotur/work, $MDBROWSE_DF). However, it doesn't disclose whether this is a safe/read-only operation or what side effects occur beyond creating the document. It adds decent behavioral context but doesn't fully cover mutation semantics.

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

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

The description is well-structured with front-loaded purpose and inline config details, but it's slightly verbose for a single tool. The branding ('the read it, keep it bridge') and substrate metaphor add flavor but not functional value. The configuration block is useful but could be more compact. Roughly 100 words for a 3-param tool is acceptable but not lean.

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

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

The tool has a clear output schema, which lightens the return-value burden. The description covers purpose, when-to-use, alternatives, defaults, and output format. For a 3-param tool with rich prose, this is reasonably complete. The main gap is the unexplained 'private' parameter and the absence of caveats about failure modes or prerequisites beyond fetch_page.

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

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

Schema description coverage is 0%, so the description must compensate. It explains corpus_root's default resolution behavior ($MDBROWSE_CORPUS_ROOT or /mnt/herfjotur/work) and the df CLI path ($MDBROWSE_DF), which adds real meaning. However, it doesn't explain the 'private' boolean parameter or how 'url' is used beyond 'capture a page.' The corpus_root and url are covered; private is not.

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

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

The description clearly states the tool's action ('Capture a page and FILE it into document-forge') with a specific verb and resource. It distinguishes from siblings by noting 'For a linked file (PDF/dataset) use download_document instead' and explicitly references fetch_page as the prerequisite. It's clear but slightly verbose with the marketing-style framing.

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 states when to use: 'Use after fetch_page when a page is worth KEEPING, not just reading.' It also names the alternative (download_document) for linked files. This is exemplary guidance that directly aids tool selection.

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

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

No annotations exist, so the description carries the full burden of behavioral disclosure. It thoroughly explains session cookie reuse, browser UA spoofing, optional referer riding, Content-Disposition naming, default save location, env var override, return values, and a fallback through the reader. This is exceptionally transparent.

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 yet every sentence earns its place by conveying concrete operational details—no filler or repetition. It front-loads the core action, then layers conditional/advanced guidance in a logical 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?

Given the tool's complexity (session auth, hotlink protection, file naming, save paths), the description covers nearly all operational needs: how/why to use, environment overrides, return values, and failure fallback. The only notable omission is the undocumented `private` parameter, which prevents a perfect score.

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

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

Schema coverage is 0% for parameter descriptions, so the description must compensate. It effectively explains referer, dest_dir, and the MDBROWSE_DOWNLOADS env var override, but it does not clarify the `private` boolean and only indirectly implies `url` as the link target. This leaves a meaningful gap in a 4-parameter schema.

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

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

The description opens with a specific verb and resource: 'Download a linked file directly to disk,' listing PDFs, spec sheets, datasets, images, and archives. It clearly distinguishes itself from siblings like fetch_page (inline reading) and download_video (media-specific), making the tool's scope unmistakable.

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 use-case guidance is provided: 'Use this when a page LINKS a document worth keeping rather than reading inline,' with a concrete example and alternative (fetch_page/page_links). It also explains when to pass referer and what to do if a WAF tarpits the direct fetch, giving clear situational context.

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

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

No annotations provided, so description carries full burden. It discloses key behaviors: muxing video+audio to mp4, extracting m4a with audio_only, default save location (~/Downloads), browser-cookie riding for gated videos, and anonymous retry fallback. Missing some detail (e.g., what happens if muxing fails), but strong coverage for a tool with zero 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?

Two dense paragraphs, zero wasted words. Front-loaded with the core purpose, then muxing behavior, then save/override options, then gated-content handling, and a closing sibling differentiation. 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?

Tool has real complexity (multiple input URL types, gated content, cookie handling, output format selection) and an output schema exists. The description covers all dimensions: what it downloads, output formats, save location, authentication/cookie handling, fallback behavior, and sibling differentiation. Complete for the tool's 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 0%, so description must compensate. It explains the audio_only=true flag (extracts m4a) and dest_dir (override save location), and reveals the MDBROWSE_DOWNLOADS env var as an alternative override. The url parameter is well-implied as a page or media URL. Doesn't cover every parameter exhaustively but the key semantics are present.

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: downloads video (or audio) via yt-dlp. Clearly distinguishes from download_document (plain files) and explains what yt-dlp handles that a plain download can't (HLS/DASH, YouTube/Vimeo, embedded players). Strongly differentiates from siblings.

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

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

Explicitly states when to use this tool vs download_document — 'Use this for a <video>/embed a user wants to keep; use download_document for a plain file (PDF, image, dataset).' Also specifies environment variables (MDBROWSE_DOWNLOADS, MDBROWSE_YTDLP_BROWSER) and retry behavior for gated content.

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

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

No annotations provided, so the description carries the full burden of behavioral disclosure. It discloses the key behavior: fetches from archive instead of live, returns clean markdown tagged with capture date. This gives the agent expectations about output format and provenance. Could go further on error behavior (e.g., when no snapshot exists), but the core behavioral profile is well covered.

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

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

Three compact sentences, front-loaded with purpose, then use cases, then output format. Zero fluff, every sentence earns its place. The second sentence explains both the 'why' and 'what you get,' and the third gives actionable routing guidance. Exemplary conciseness for a tool description.

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

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

The tool has a clear purpose, a strong routing recommendation against a named sibling, and clean output ('clean markdown, tagged with its capture date'). With an output schema present, return-value details don't need elaboration. Given the moderate complexity and strong supporting signals, the description is complete for an agent to select and use it correctly.

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

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

Schema description coverage is 0%, and the description mentions no parameters explicitly. However, only one parameter is required (url), and the prompt suggests max_chars/start_char relate to pagination within the markdown (defaults given). Since the description doesn't explicitly explain these params, it relies on the schema's defaults and naming. Behavior of max_chars/start_char is intuitive from names — with 0% coverage but 3 simple params, the description could add a bit more, but the schema defaults carry reasonable 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?

Specific verb+resource: 'Fetch a page from the Wayback Machine (archive.org) instead of live.' Clearly states what it does and differentiates from the sibling 'fetch_page'. Explicitly mentions the output ('clean markdown, tagged with capture date') and problem cases, which distinguishes it well from related archive tools like 'archive_search' and 'archive_page'.

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

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

Provides explicit when-to-use guidance: 'Reach for this when fetch_page returns a wall, or when you want the historical version' with concrete scenarios (bot walls, IP-blocked sites, dead links, changed content). Names the specific sibling alternative (fetch_page) and the condition under which to prefer this tool. Strong guidance for agent selection.

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

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

With no annotations provided, the description carries the full disclosure burden and does it well: it details auth mode (Safari cookies default, private for anonymous), pagination behavior with start_char, deterministic hashing, and that backend selection is never silent. It even discloses truncation tail markers. Minor gap: no explicit statement of destructive/side-effect behavior (e.g., whether fetching stores data permanently), but overall disclosure 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 five dense paragraphs covering substantial complexity (headless rendering, shape classification, determinism, auth, pagination, backend fallback). It front-loads the core purpose in the first sentence, then layers detail. A little tabular or bulleted structure for params and backend options would improve scannability, but given the complexity, the prose is appropriately 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?

This is a complex, 7-parameter tool with no annotations and 0% schema coverage, yet the description covers rendering semantics, determinism, auth modes, pagination, shape behavior, and backend selection. An output schema exists (documenting return values), so the description needn't explain them. The main residual gaps are the exact list of valid backend values and a systematic param-by-param mapping, but for the complexity level it's remarkably 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 description coverage is 0%, so the description must compensate, and it does for several params: private (anonymous fetch vs Safari cookies), wait_selector (SPA late-paint handling), start_char (pagination slicing), backend and allow_external_fallback (backend selection). However, url, max_chars, and the specific syntax/format of backend values (native/opencli/twitter-cli) aren't documented in a systematic way. Coverage is good but not exhaustive given 7 params.

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

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

The description opens with a specific, vivid purpose: 'Fetch a web page as clean, deterministic markdown with provenance.' It distinguishes itself from siblings by detailing headless-browser rendering, shape classification, YAML front-matter, and hash-based determinism. This clearly differentiates it from archive_search, fetch_archived, download_video, and page_links.

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

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

The description provides explicit when-to-use guidance: private=true for anonymous fetches, wait_selector only for late-painting SPAs, and clear notes on feed vs article page shapes. It also explains backend fallback behavior when native capture is gated on a covered URL, directing users to backend='opencli'/'twitter-cli' or allow_external_fallback=true. This is strong alternative-and-condition guidance.

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

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

No annotations are provided, so the description carries the full burden. The description does disclose the two main behaviors: what gets returned (form details + loose search boxes) and the GET-form simplification. However, it doesn't disclose edge cases like pages with no forms, JavaScript-rendered forms, or handling of malformed HTML, leaving some behavioral ambiguity.

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

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

The description is two paragraphs and is front-loaded with the core purpose. Every sentence earns its place — the first paragraph defines the tool and its role, the second gives a practical alternative. Slightly verbose in the field enumeration but no wasted sentences.

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

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

For a read-only inspection tool with no output schema and no annotations, the description is fairly complete: it lists what fields are returned, its relationship to submit_form, and a pragmatic GET-form simplification. It could be more complete about the 'private' parameter, but overall it covers the key usage scenarios well.

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

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

Schema description coverage is 0%, so the description must compensate for the two params (url, private). The description describes 'on a page' referencing the url parameter contextually, but it doesn't explicitly document what each parameter means or how 'private' alters behavior. For a 2-param tool, this is a modest gap rather than a severe one.

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 has a specific verb+resource ('List the fillable forms on a page') and clearly enumerates exactly what's returned: method, action, submit-button label, fields (name, type, placeholder, label, select options), plus loose search boxes. It clearly distinguishes from sibling fetch_page and submit_form by stating this is the 'OBSERVE step before submit_form'.

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?

Excellent when-to-use guidance. It explicitly states this is the OBSERVE step to call before submit_form to learn field names. It also provides a clear when-NOT-to-use alternative: for GET forms, fetch_page with a query in the URL is simpler. This directly differentiates from sibling fetch_page and submit_form.

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

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

No annotations provided, so the description carries full behavioral burden. It discloses a significant behavioral trait: the 60s cache share with fetch_page, meaning calling both costs one page render. This is genuinely useful operational context. It also documents the pattern matching behavior (case-insensitive regex on text OR href). However, it doesn't disclose rate limits, auth needs, or what happens when max_links is exceeded.

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 with zero filler. Each sentence adds value: format+ordering, use-case guidance, concrete pattern example, and caching behavior. The pattern example is inline and efficient. Front-loaded with the core behavior, then supporting 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 no annotations, the description does substantial lifting. It specifies output format, ordering, caching behavior, and a concrete pattern example. For a link-listing tool this is fairly complete. Minor gaps (max_links semantics, private parameter purpose) but the tool's behavior is well-specified for an agent to reason about correct usage.

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

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

Schema coverage is 0%, meaning the description must compensate for the 4 parameters. It does explain 'pattern' in detail with a concrete example (pattern="item\?id=" for HN comment pages) and documents text OR href filtering. But 'max_links', 'private', and 'url' are not explained beyond the schema. The baseline of 3 applies since the schema has defaults but the description only partially supplements the parameters.

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?

Description states a specific verb+resource+behavior: 'List a page's links as [{text, href}, ...] in document order.' The mention of document order and the structured output format clearly distinguishes this from the fetch_page sibling, which would return full markdown. It also explains the value proposition ('Cheaper to reason over...').

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 contrasts with fetch_page by explaining when to prefer links vs full markdown ('Cheaper to reason over... when deciding where to navigate next'). It shares a capture with fetch_page so an agent understands a caching relationship, which is useful context. However, it doesn't explicitly state when NOT to use it (e.g., when you need page content beyond links) or name alternatives like search_web.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals key operational details: that searches ride Safari cookies (so results may reflect authenticated sessions), that the engine is configurable via environment variables, and the output format. However, it doesn't disclose rate limiting, pagination behavior, or what happens on empty 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?

The description is tightly written and front-loaded with the core purpose. The engine/cookie detail is valuable behavioral context but adds length beyond the essentials. Every sentence earns its place, though the format and follow-up guidance could arguably be split for clarity.

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 low schema coverage (0%), an output schema exists, and no annotations, the description does substantial work but omits parameter semantics entirely. It covers purpose, output format, engine configuration, and workflow, which is solid for a read-only search tool. The missing parameter explanations for private and max_chars leave a notable gap, but the output schema presumably documents the return structure.

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

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

Schema coverage is 0%, so the description must compensate for all three parameters, but it only mentions the query indirectly. The description doesn't explain what 'private' or 'max_chars' do. The engine configuration context is useful but doesn't address parameter semantics. Since the description does not document any parameter meaning, this scores at baseline for a low-coverage case but not higher.

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

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

The description states a specific verb-resource pair ('Search the web') with clear output format ('results come back as markdown, one linked line per result'). It distinguishes from siblings by explicitly naming fetch_page as the follow-up tool, which differentiates searching from fetching pages.

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

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

The description provides clear context for when to use this tool ('search the web') and explicitly directs the agent to 'follow up with fetch_page on the results worth reading,' naming the alternative/next-step tool. It doesn't describe exclusions or when NOT to use it versus archive_search, but it identifies the natural workflow distinction between search and page retrieval.

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

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

With no annotations provided, the description carries the full disclosure burden. It does well: states it returns the result page, rides the user's session (privacy-relevant behavior), and explains the submit fallback behavior. It doesn't address rate limits or destructive potential, but the tool is primarily a form-submission action with benign scope; the session and Enter-fallback disclosures add meaningful value beyond schema.

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

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

The description is dense and richly informative, with concrete examples and front-loaded purpose. It's somewhat long but every sentence earns its place—covering pipeline, fields mapping, submit behavior, session, and usage guidance. The only mild inefficiency is the slightly repetitive closing paragraph about use cases.

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 6 params with 0% schema coverage and no annotations, the description covers the core ones well and references the parent pipeline. An existing output schema lightens the return-format burden. It could add a bit more on private/max_chars and error conditions, but for a mid-complexity form tool it's largely 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 description coverage is 0%, so the description must explain the parameters, which it does well. It explains 'fields' with concrete mapping examples (label→value), clarifies 'submit' semantics and its default fallback (Enter in last field), and for max_chars/wait_selector/private/url it implies meaning through the fetch_page pipeline reference. A tiny gap: private and max_chars are not individually described, but the framework reference partially compensates.

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

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

The description clearly states the tool fills forms on a URL and returns the result page as markdown. It explicitly names the resource (form on url), the verb (fill/submit), and distinguishes it from siblings like fetch_page (simple GET) and page_forms (discovery). The examples and the search-box convention make the purpose unmistakable.

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 tells when to use this tool over alternatives: 'Discover field names first with page_forms(url)', recommends fetch_page for simple GET searches ('lighter'), and enumerates the use cases it unlocks (site search, faceted browsing, GET/POST/JS forms). It also documents the session-riding behavior for logged-in forms.

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

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

No annotations are provided, so the description carries the full burden. It does disclose key behavioral traits: first snapshot is git-committed to the watch store, fires only when visible text changes, link-token churn never false-fires, and name defaults to a URL slug. However, it doesn't explain what the return value is, how to stop/remove a watch, or any limits on concurrent watches. Reasonable transparency but gaps remain for a tool with zero annotations and no output schema.

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

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

The description is economically written in a single concise paragraph, front-loads the core purpose, and every clause adds meaningful information. Minor inefficiency in slightly awkward phrasing ('let later watch_scan calls fire when...'), but no wasted words or redundancy.

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

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

The tool has 3 parameters with 0% schema coverage and no annotations or output schema, so the description must compensate heavily. It explains the watch mechanism well and distinguishes from watch_scan, but leaves 'private' semantics unexplained, doesn't describe what the tool returns, and doesn't address how the watch integrates with watch_list/watch_diff/watch_remove. Adequate for basic use but incomplete for a tool that creates persistent state.

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

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

Schema description coverage is 0%, meaning all 3 parameters (url, name, private) are undocumented in the schema itself and there are no parameter descriptions. The description mentions 'Name defaults to a slug of the URL' (clarifying the 'name' parameter's default behavior), which adds some value, but 'url' and especially 'private' are completely unexplained — the semantics of the private flag are entirely opaque.

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

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

The description states a specific verb+resource ('Start watching a URL for real content change'), explains the core action (takes snapshot now, fires later on visible text change only), and distinguishes from the sibling watch_scan tool by noting when scan fires. Clear and precise.

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 explains the mechanism (initial snapshot, subsequent fires on visible text change) which implies when this should be used (to monitor content change). However, it doesn't explicitly state when NOT to use it or name alternative tools, though watch_scan is implicitly contrasted. Decent implied guidance but no explicit exclusions or named alternatives for differing use cases.

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

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

The description adds useful context: it's read-only (returning a patch, no mutation implied), and it's scoped to the 'most recent' change, which is a meaningful behavioral constraint. However, it doesn't disclose things like whether the patch is partial/full, whether there's a limit on patch size, or whether all diff formats are git-specific. Since there are no annotations, the description carries the transparency burden but delivers moderate 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?

The description is two sentences with zero wasted words. It front-loads the core function (git patch of most recent change) and then gives a sequencing tip. Every clause adds value.

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 it has an output schema, return values don't need explanation. The description covers purpose, timing (after watch_scan), and content (patch format). For a single-parameter tool with output schema, this is near-complete. Minor gaps: doesn't explain the 'name' parameter explicitly, but the low parameter count and coherent description compensate.

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

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

With only one parameter (name) and 0% schema description coverage, the schema provides no semantics. The description implies the tool operates on a named watch but doesn't explicitly state that 'name' refers to the watch name/identifier. The context of 'a watch' plus the single 'name' parameter makes this reasonably inferable, but explicit confirmation would strengthen the parameter documentation.

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

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

The description clearly states the tool returns 'a watch's most recent change as a git patch' with line annotations. It uses specific verbs and resource ('watch' + diff/patch), and the reference to 'what moved' clarifies the diff nature. It distinguishes from siblings like watch_scan and watch_list by specifying it shows the patch content rather than status.

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

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

The description gives explicit usage context: 'Use after watch_scan reports changed to see exactly what moved.' This clearly tells the agent when to invoke this tool in sequence. However, it doesn't state when NOT to use it or name explicit alternatives, though the sequencing guidance covers the primary use case well.

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

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

No annotations are provided, so the description carries the full burden. It's a read-only list operation implied by the phrasing 'List configured watches', which is clear. It discloses what fields are returned (name, url, mode, last checked, last changed), providing useful behavioral context about the output even without an output schema. Being a no-arg read is self-evidently safe.

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, well-structured sentence that front-loads the action (List) and immediately enumerates the output fields. Zero waste, every word contributes meaning. Perfectly sized for a zero-argument tool.

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

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

For a zero-parameter, read-only list tool with no output schema, this description is complete. It names the operation and enumerates all output fields. There's no complexity requiring more. The only minor gap is that it doesn't hint at sorting/ordering or whether results differ from watch_scan output, but this is adequate.

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

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

The tool has zero parameters, and schema coverage is 100% (there is nothing to document). The description doesn't need to explain parameters since there are none. The baseline 4 for zero-parameter tools applies here.

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

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

Clear verb+resource: 'List configured watches' with specific fields enumerated (name, url, mode, last checked, last changed). Distinguishes from siblings since watch_add, watch_remove, watch_scan, and watch_diff are all actions while this is a list operation, though it doesn't explicitly name any sibling.

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

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

The description implies it's for viewing configured watches, and the sibling set makes the listing-vs-mutation contrast implicit. However, it doesn't explicitly state when to use this vs alternatives, nor does it note that it's the read-only complement to watch_add/watch_remove. No exclusions or prerequisites given.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It does disclose one meaningful behavior: that snapshot history remains in the git log after removal, which helps an agent understand this is not destructive to historical data. However, it doesn't disclose whether the operation is reversible (whether re-adding is needed), side effects on ongoing scans or diffs, or what happens to watch-list state. The partial disclosure earns a mid-range score but leaves 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?

The description is very concise — two short sentences with zero filler. It's front-loaded with the primary purpose and adds one valuable behavioral detail. Appropriately sized for a simple 1-parameter tool.

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

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

For a simple single-parameter tool with no output schema and no annotations, this is on the lower end of adequate. The description covers the core action and one consequential behavior, but given the absence of all structured metadata, it should say more about the 'name' parameter format and the relationship to watch_add/watch_list to be fully complete for an agent deciding to invoke it.

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

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

There is only one parameter (name) with 0% schema description coverage, so the description must compensate. The description implies 'name' refers to the identifier of the page to stop watching, but it doesn't specify the naming convention (URL, title, slug, internal ID) used by sibling watch tools. Since schema coverage is 0%, a brief note on what 'name' refers to would be valuable; its absence keeps this at baseline 3.

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

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

The description clearly states the verb ('Stop watching a page') and the resource (a page being watched), making the core purpose evident. However, it doesn't differentiate from siblings like watch_add or watch_list, and the purpose of 'watching' itself is implied rather than explained. The description is clear enough to understand the action but lacks explicit scoping or distinction from closely related watch operations.

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 context (action on a page currently being watched, likely paired with watch_add), but provides no explicit when-to-use or when-not-to-use guidance, and doesn't name any alternative tools. Siblings like watch_list, watch_scan, and watch_diff exist, but the description offers no guidance on choosing among them. The stated behavior that snapshot history persists could be seen as a reassurance cue, weakly implying this tool is safe when history retention matters.

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

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

With no annotations provided, the description carries the full burden and does well. It discloses a critical behavioral trait: changes are detected on visible text only, meaning a 'changed' reading signifies a reader would agree the page changed. It also clarifies that 'snapshot committed' on changed and reports 'why' on error. This is meaningful behavioral context beyond what structured fields would provide.

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 compact (two sentences) and front-loaded with the core action and the three status outcomes. Every sentence earns its place — the visible-text detection detail and empty-names behavior are both useful. Slightly dense with the parenthetical explanations but no wasted words.

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

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

For a single-parameter tool with no output schema, the description covers the action, the result statuses, the return-field example (diff_sample), the default behavior, and the critical scoping constraint (visible text only). This is fairly complete for the tool's simplicity. It could have noted the need for prior watch_add setup, but the sibling structures make that inferable.

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

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

Schema coverage is 0% and there is only 1 parameter (names, an array with no item type specified). The description compensates somewhat by noting 'Empty names scans everything,' which clarifies the default/empty behavior of the names parameter. However, it doesn't explain what the array items should be (watch identifiers? names?), leaving ambiguity about how to populate the parameter.

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

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

The description clearly states the tool re-fetches watches and reports one reading each (ok/changed/error), distinguishing its monitoring/scanning purpose from sibling tools like watch_list (lists watches) and watch_diff (shows diffs). It's specific about the verb and resource ('re-fetch watches') and the three possible outcomes. However, it doesn't explicitly distinguish it from watch_diff, which is a close sibling.

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

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

The description states 'Empty names scans everything,' giving useful default behavior, and explains the semantics of each result status. However, it doesn't explicitly say when to use this vs watch_diff or watch_list, nor does it mention any prerequisites (e.g., must have watches added first via watch_add). Usage context is implied but not explicitly contrasted with alternatives.

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