Rendex: Rendering API for Images, PDFs & Content Extraction

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds important behavioral context: each requested format costs 1 render credit, and the tool returns hosted URLs (pdfUrl, pngUrl, shareUrl, expiresAt). This goes beyond the annotations and helps agents understand side effects and cost implications.

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 three sentences, front-loaded with the primary use case, followed by an exclusion and the return value summary. Every sentence adds value, and there is no repetition of schema details. It is concise yet comprehensive for orientation.

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 (11 parameters, nested pageSetup object) but a fully documented schema, the description provides enough context for initial selection: it defines the core output (PDF + PNG + share page), mentions branding options, and states the return format and credits. It does not cover every nuance (e.g., Mustache templating, pageSetup defaults), but the schema fills those gaps, making this a complete high-level 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 description coverage is 100%, so the input schema already documents all 11 parameters and nested objects in detail. The description adds minimal parameter info beyond naming logo, accentColor, font, header, and footer as branding fields, which is helpful but not substantial. It does not explain the Mustache templating in the 'data' parameter, but that is covered by the schema.

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

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

The description clearly states the tool's purpose: converting Markdown or HTML into branded PDF/PNG artifacts with logo, accent color, font, header, and footer. It uses specific verbs ('turns', 'create') and explicitly distinguishes itself from rendex_screenshot, preventing confusion with sibling tools.

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

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

The description opens with 'Use this when...' and gives concrete triggers (user asks for a branded report, invoice, summary, or to convert Markdown/HTML to PDF/PNG). It also states a clear exclusion: 'Do NOT use to screenshot an existing URL (use rendex_screenshot)', naming the alternative tool.

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 read-only and idempotent, and the description adds valuable behavior context by outlining exactly what information is returned and explicitly stating 'Read-only — costs no credits.' This goes beyond the safety hints, though it does not describe edge cases or failure modes.

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, front-loaded with the core purpose, and every clause adds meaningful detail (plan, credits, limit, reset, rate limit, upgrade link, usage cue, credit cost). No redundancy or filler.

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

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

With zero parameters, strong annotations, and no output schema, the description covers all necessary context: what the tool checks, what specific data it returns, when to use it, and its safety profile. It fully compensates for the lack of an output schema.

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, so the description carries no parameter burden. Per guidelines, 0 params earns a baseline of 4, and the description appropriately focuses on the tool's purpose and outputs rather than nonexistent inputs.

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 action ('Check the Rendex account') and enumerates distinct outputs: plan, credit usage vs monthly limit, reset time, per-minute rate limit, and upgrade link. This clearly distinguishes it from sibling tools like render_artifact or watch_list.

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

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

Explicitly states when to use it: 'whenever the user asks about their usage, remaining quota, current plan, or how to get more renders / stop hitting limits.' This provides clear context for tool selection and even notes it costs no credits.

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 readOnlyHint/openWorldHint annotations, the description reveals meaningful behavior: it 'Runs the same Chromium render pass as a screenshot, so it captures content after JavaScript runs — handles SPAs that fetch-only readers miss,' and it 'Strips nav, ads, and boilerplate.' It also discloses the cost: 'Costs 1 render credit per call.' 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 concise and front-loaded: it begins with the trigger condition, then the exclusion, then the core behavior and output, then use cases and cost. Every sentence adds distinct value — none are generic or repeated. It is structured for quick parsing by an AI agent.

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

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

With no output schema, the description compensates by specifying what is returned ('article body plus title, byline, and excerpt') and the formats available (Markdown, JSON, HTML). It also covers important caveats like JavaScript rendering, SPA support, and render credit cost. The parameter schema handles the rest, making this 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 100% — all 8 parameters have detailed descriptions, so the schema does the heavy lifting. The description adds high-level context (e.g., 'Strips nav, ads, and boilerplate' relating to blockAds/blockCookieBanners) but no parameter-level syntax or format details beyond what the schema already provides. Baseline 3 applies.

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

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

The description opens with a specific trigger: 'Use this when the user asks to read, extract, get the text/content/article of, or summarize a webpage/URL.' It clearly names the resource (webpage) and the action (extract reader-mode content), and distinguishes itself from the sibling tool by explicitly directing screenshot requests to rendex_screenshot.

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 ('when the user asks to read, extract, get the text/content/article of, or summarize a webpage/URL') and when not ('Do NOT use for a visual screenshot (use rendex_screenshot)'). It also provides additional context by mentioning ideal use cases: 'Great for feeding page content to an LLM, summarization, or RAG ingestion.'

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 (readOnlyHint, openWorldHint, etc.), the description adds valuable behavioral details: it returns a signed, hosted, edge-cached URL; it costs 1 render credit per fresh render and cached hits don't re-charge; and it specifies the JSON return shape. These are meaningful traits not covered by annotations. It does not contradict the readOnlyHint because consuming credits is not a data mutation. A small gap: it doesn't detail caching invalidation or error cases, but the provided context is solid.

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

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

The description is front-loaded with the primary use case, then explains behavior and costs. It's a few sentences long and each sentence adds new information (when to use, when not, return shape, credit cost). It is efficient but not as tight as a two-sentence description, hence a 4 instead of a 5.

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

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

Given the tool's complexity (38 params, nested objects, no output schema), the description covers the essential missing context: it explicitly states the return format { url, expiresAt, format, cacheTtl }, the credit cost, and the shared parameter base with rendex_screenshot. This compensates for the absent output schema. It could have mentioned error scenarios or additional limitations, but the inclusion of return shape and caching makes it sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does little to explain individual parameters, only noting it shares options with rendex_screenshot and adds expiresIn. Since every parameter is fully described in the schema, the description doesn't need to add much; it does not actively reduce clarity.

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 purpose: it mints a reusable, hosted image URL rather than returning image bytes. It specifically says 'Use this when the user wants a reusable, HOSTED image URL — an og:image or a link to embed in an <img> tag' and contrasts with the sibling rendex_screenshot, making the tool's identity and differentiation 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?

Usage guidance is explicit: 'Use this when...' for hosted URLs and 'Do NOT use for a one-off inline screenshot (use rendex_screenshot).' It also mentions that it accepts the same options as rendex_screenshot plus expiresIn, giving clear context on when to choose this tool over its sibling. This is a model of when/when-not guidance.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds meaningful behavioral detail beyond that: it returns partial renders on timeout by default, costs 1 render credit, uses progressive fallback for heavy sites, and requires specific plans for certain features (Starter+ for cookie/header injection, Pro+ for geo-targeting). No contradiction with annotations exists.

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 yet information-dense: it front-loads the trigger condition, then gives exclusions, a capability list, then behavior, cost, and access restrictions. Each sentence earns its place, and the structure guides the reader from selection to execution.

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

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

Despite having 37 parameters, no output schema, and considerable complexity, this description covers selection criteria, sibling distinctions, key behaviors (bestAttempt, fallback), cost, and plan limitations. The only minor gap is the exact output delivery format, but the tool title and phrasing ('captures a screenshot or PDF') make the return type sufficiently clear for an agent to select and invoke the 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?

The input schema has 100% parameter coverage with rich per-property descriptions (e.g., Mustache templating for 'data', 'waitUntil' semantics, PDF margin details). The description adds only a high-level capability summary without introducing parameter-level meaning beyond what the schema already provides, so the baseline score of 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 opens with explicit trigger phrases ('screenshot, capture, or take a picture of a webpage/URL') and clearly states the tool 'Captures a screenshot or PDF of any webpage, raw HTML, or Markdown.' It also names sibling tools (rendex_render_link, render_artifact) and explains exactly what this tool is NOT for, making distinction among siblings unambiguous.

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

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

The description provides explicit when-to-use guidance ('Use this when the user asks to...') and when-not-to-use guidance with named alternatives ('Do NOT use to get a reusable hosted image URL...'). It also gives operational context: cost per call, plan requirements for cookie/header injection and geo-targeting, and the default bestAttempt fallback behavior.

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 indicate readOnlyHint=false and destructiveHint=false, so mutation is communicated. The description adds behavioral context beyond annotations: the watch runs on a schedule, notifies upon changes, captures a baseline immediately, and returns JSON. It doesn't contradict annotations. It lacks details on cost or lifecycle but provides useful transparency for a mutation 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?

The description is four sentences: usage trigger, exclusion with alternative, core function with details, and return format. It is front-loaded, each sentence adds distinct value, and there is 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?

Given the tool's complexity (10 params, nested object, no output schema), the description adequately covers purpose, usage, a concise explanation of diff modes (visual/text/both), and the return type. It doesn't explain lifecycle costs, but those are documented in parameter descriptions (e.g., paused, plan floors). The description is sufficient for an agent to select and 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?

The input schema has 100% description coverage for all 10 parameters, including detailed semantics for fields like 'paused', 'diffMode', 'threshold', and the nested 'renderParams'. The description itself adds minimal parameter guidance, only mentioning that an active watch captures a baseline. Since the schema is comprehensive, a baseline of 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 clearly states the tool's purpose: 'Creates a Rendex Watch — monitors a URL on a schedule and notifies when it changes'. It also differentiates from sibling tools with the explicit directive: 'Do NOT use for a one-time capture (use rendex_screenshot)'. This is a specific verb+resource with clear scope.

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 usage context: 'Use this when the user asks to monitor, watch, or track a webpage for changes, or to be alerted/notified when a page changes' and an explicit exclusion with an alternative tool: 'Do NOT use for a one-time capture (use rendex_screenshot)'. It also notes the baseline capture behavior, giving actionable guidance.

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

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

The annotations already declare destructiveHint=true, but the description adds critical context by specifying that both the watch and its run history are deleted and that the action is 'Irreversible'. This goes beyond the minimal annotation, providing behavioral transparency about the extent and permanence of the operation.

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

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

The description is extremely concise: two short sentences with no filler. It front-loads the core function ('Delete a watch') and includes the critical caveat ('Irreversible') in the second sentence. Every word 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?

Given the low complexity (one parameter, no output schema) and the strong annotations, the description is nearly complete. It covers the action, scope, and irreversibility. The only minor omission is not mentioning idempotency, but that is already covered by annotations (idempotentHint=true). Overall, sufficient for correct use.

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

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

The schema description covers 100% of the single parameter (id) with a clear explanation. The tool description itself does not add any extra parameter semantics, but given the high schema coverage, a baseline of 3 is appropriate. No new meaning beyond the schema is provided.

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 action ('Delete'), the resource ('a watch'), and the additional scope ('and its run history'). This distinctly identifies the tool as the deletion operation among sibling tools like watch_create, watch_update, and watch_list, leaving no ambiguity.

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

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

The description implies usage by saying 'Delete', but it does not explicitly state when to use this tool versus alternative actions like disabling a watch or seeking a soft-delete option. No exclusions or alternatives are mentioned, so the guidance is only 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?

Annotations already declare it read-only, idempotent, and non-destructive, so the description need not repeat those. It adds useful context by specifying that the response is JSON and includes the current baseline image URL and status, which are not in the annotations.

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

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

The description is a single sentence that front-loads the verb and object, states the key output fields, and includes the response format. There is no wasted wording or unnecessary 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 simple single-parameter read operation, the description is sufficiently complete: it identifies the input, the output format, and the key fields returned. Error behavior is not mentioned, but given the simplicity and strong annotations, this is a minor gap.

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

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

The input schema has 100% coverage and already explains that 'id' is a UUID. The description adds no additional semantic meaning beyond repeating the ID reference, so the baseline score of 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 uses a specific verb and resource ('Fetch one watch by ID') and clarifies scope ('one watch') and key outputs ('baseline image URL and status'). This clearly distinguishes it from sibling tools like watch_list, which would fetch multiple watches.

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 clearly implies the tool is for retrieving a single watch by its ID, which is the correct context. It does not explicitly name alternatives or when-not-to-use, but the singular 'one watch by ID' provides adequate guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds useful behavioral context: ordering ('newest first') and return shape ('Returns { items, nextCursor }'), but these are modest additions beyond what 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?

The description is two sentences, front-loaded with the action verb 'List', and includes only essential details (ordering, filtering, pagination, return shape). No filler 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?

For a simple list tool with robust annotations and full schema coverage, the description is complete. It specifies the return shape ({ items, nextCursor }) and pagination behavior, which is sufficient given no output schema. The sibling tool names provide additional context for differentiation.

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 input schema has 100% description coverage, with all three parameters (limit, cursor, status) already explained. The description mentions 'filtered by status' and 'paged' but adds no extra meaning beyond the schema, so the baseline of 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 uses a specific verb+resource construction: 'List your watches' with added scope ('newest first', 'optionally filtered by status and paged'). It clearly distinguishes itself from sibling tools like watch_get (single watch) and watch_runs.

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 the tool: listing watches with optional filtering and pagination. However, it does not explicitly mention alternatives or exclusions (e.g., 'for a single watch, use watch_get'), so it falls short of a 5.

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

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

Beyond the annotations (which only signal non-read-only, non-idempotent, non-destructive), the description discloses critical behaviors: the operation charges 1 credit, and it returns a 'queued run' rather than the final result, meaning the actual result must be obtained via polling or webhook. This async behavior and cost implication are essential and not present in 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 a single, front-loaded sentence with no filler. It packs the action, cost, immediate return, and follow-up retrieval method into one concise statement.

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

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

For a one-parameter tool with no output schema, the description is complete: it explains what it does, what it returns (queued run), how to get the actual result (poll or webhook), and the cost. No important behavioral aspect 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?

Schema description coverage is 100% with the id parameter well-described as 'The watch ID (UUID)'. The tool description does not add any additional parameter meaning, but given full schema coverage, the baseline of 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 clearly states the action: 'Run an immediate check now', identifying the specific resource (a watch run) and scope (immediate). It distinguishes itself from sibling tools by noting you must 'poll watch_runs for the result', which differentiates the triggering action from the retrieval action.

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 conveys clear usage context: this is for running an immediate on-demand check, as opposed to scheduled or automated runs. It also guides the next step by pointing to watch_runs or webhook for result retrieval, but it does not explicitly state when not to use this tool or name direct alternatives like watch_test.

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 agent knows this is a safe read operation. The description adds substantial context beyond the annotations: it specifies that runs are ordered newest-first, paged, and details the content of each run (changed, diffScore, signed image URLs) plus the response structure { items, nextCursor }. This provides a clear picture of behavior without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the core purpose, and includes only relevant details about content and response shape. No word is wasted.

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 paginated list tool with no output schema, the description covers the essential return structure and element fields. It specifies ordering, paging, and the cursor mechanism. Given the richness of annotations and schema, 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?

The input schema documents all three parameters (id, limit, cursor) with descriptions, achieving 100% coverage. The description references pagination via the nextCursor return but does not add new meaning to the parameters beyond what the schema already provides. Thus the baseline of 3 for high schema coverage 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 uses the specific verb 'Read' to identify the operation, clearly specifies the resource as 'a watch's run history', and includes ordering and paging behavior. It distinguishes from siblings like watch_list (which likely lists watches) and watch_get (which gets a single watch) by focusing on run history.

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 does not explicitly state when to use this tool vs alternatives, nor provide any exclusions or alternative tool references. However, the function is clear from the description and sibling tool names, making usage context implied. There is no explicit guidance for selecting between watch_run, watch_get, and watch_runs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Creates no watch, no baseline, no diff.' It adds behavioral details beyond annotations by specifying the report content: 'what was captured + whether the page is reachable (and the text a text-watch would compare).' 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 four sentences that front-load the purpose ('Dry-run a watch config BEFORE creating it'), then add critical side-effect information and usage guidance. It is concise, with no wasted words or repeated schema content.

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

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

The tool has no output schema, so the description carries the burden of explaining return values. It covers key aspects: 'what was captured', 'whether the page is reachable', and 'the text a text-watch would compare', plus 'Returns JSON'. However, given the complexity (10 params, nested renderParams), a more explicit output structure or further details would make it more complete, but it is adequate for a dry-run validation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'render the proposed config once' and 'text a text-watch would compare' loosely references renderParams and diffMode, but it does not add meaning beyond the schema's thorough per-parameter descriptions. The schema already documents all parameters in detail.

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

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

The description clearly states the tool's purpose: 'Dry-run a watch config BEFORE creating it'. It uses a specific verb ('dry-run') and resource ('watch config'), and distinguishes itself from siblings by explicitly stating 'Creates no watch, no baseline, no diff', which differentiates it from watch_create and watch_run.

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 clear usage context: 'BEFORE creating it' and 'Use this to validate a selector/scope/identity first.' It implies the alternative is actual creation, and the sibling list includes watch_create and watch_run, which helps disambiguate. However, it does not explicitly name alternatives or state when not to use it.

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

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

Annotations establish readOnly=false, destructive=false, idempotent=true; the description adds meaningful behavioral details beyond that: renderParams deep-merge semantics, scope-change re-baselining, and null values disabling channels. This goes beyond what annotations 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?

Three compact sentences; the first sentence front-loads the tool's purpose and key actions, the second clarifies update semantics, the third covers re-baselining and return value. No redundant content.

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

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

For an 11-parameter tool with nested objects, the description covers the essential behavioral contract: partial update, merge behavior, re-baselining, and return type. It doesn't enumerate every parameter, but the schema already does; the description adds the higher-level logic needed to use 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?

The schema already documents all 11 parameters with 100% coverage. The description adds cross-cutting semantic context that the schema cannot: partial-update behavior ('Only the fields you send change'), deep-merge for renderParams, and the re-baseline trigger for scope-related params. This is a slight but real lift above the schema baseline.

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

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

The description opens with a specific verb ('Update') and resource ('a watch'), enumerating concrete update actions (pause/resume, re-point, change settings, turn off channels). This clearly distinguishes it from sibling tools like watch_create and watch_delete.

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 establishes it as the in-place modification tool for existing watches, with explicit semantics for partial updates ('Only the fields you send change'). It does not explicitly name alternative tools, but the 'in place' framing and update verb make the usage context unambiguous.

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