HTML/CSS to Image API

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds some context beyond that by detailing the exact return fields and the meaning of overages_enabled. However, it does not disclose behavior like API rate limits or caching, but given the tool is simple and read-only, the description sufficiently supplements the annotations without contradiction.

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

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

The description is three sentences long, tightly packed with useful information. It leads with the core purpose)Skip the exact fields returned, then provides practical usage guidanceches and an interpretation of the fields. Every sentence contributes significant value without 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?

Given that the tool has no parameters and a read-only nature, the description is fully complete. It explains the output fields and their semantics, and it mentions usage scenarios. The presence of an output schema further fills in structural details, so nothing essential is missing for an agent to invoke and interpret 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 tool has zero parameterschers, so the description's job is to explain the output, which it does thoroughly. It defines what each field means and how to interpret them (e.g., the formula for remaining credits). This adds substantial value beyond the schema, which is empty.

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 returns the organization's current image-credit usage, listing the specific returned fields. This is distinct from sibling tools that focus on creation, deletion, or listing of resources, making it clearly identifiable as a read-only utility.

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 says when to use it: 'to check capacity before rendering or explain a usage-limit error.' This provides clear context for use, and although it doesn't name specific alternatives, the purpose is so unique that the agent can infer it is the go-to for usage queries, distinguishing it from sibling tools that manage assets.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description adds genuinely useful behavior beyond them: the default/variation merge rule and the plan-limit gating via get_max_batch_size. It does not elaborate on what the destructive aspect means for existing assets, which keeps it short of a 5.

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

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

Five short sentences, each carrying a distinct load: purpose, prerequisite, limit rule, merge semantics, and return shape, with the alternative-tool guidance last. Nothing is padded and the primary purpose is front-loaded.

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

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

For a two-parameter tool with a full output schema, the definition covers everything an agent needs: the prerequisite call, the limit-0 fallback, the override relationship, the response fields (item), and the sibling alternative. Return-value details are not required since an output schema exists, yet the brief mention adds orientation without bloat.

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

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

Schema description coverage is 100%, and the schema's own variations description already states that supplied parameters override default_options, so the description's merge sentence largely repeats structured data. It adds the useful batch-level framing but no new per-parameter syntax or constraints, matching the baseline for fully documented schemas.

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 ('Creates multiple image assets') and immediately frames the two-parameter model (shared default_options + individual variations). It also names the sibling alternative ('individual creation tools'), so an agent can distinguish it from create_image and create_url_image without opening schemas.

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

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

Explicit prerequisites and routing rules: 'Call get_max_batch_size first', a returned limit of 0 means fall back to individual image calls, and single-image or inline-preview needs should use the individual tools. This covers when-to-use, when-not-to-use, and which alternative to pick.

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

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

Adds substantial context beyond annotations: merge semantics ('Shared template_values merge recursively... arrays, scalars and explicit null replace defaults'), template_id/version reset behavior, deduplication ('Identical images reuse existing assets'), and return format. Doesn't contradict annotations. Missing explicit statement about the destructiveHint=true implication (e.g., overwrite semantics) and plan limit details, but otherwise covers behavioral traits well.

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

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

Dense but front-loaded: core purpose first, then operational constraints. Every sentence carries information, though the description is somewhat long and could be structured with bullets for the merge rules. No filler.

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

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

Output schema exists, so return value explanation isn't required, yet the description still notes 'Returns IDs, URLs and format information in response order' which is helpful. Covers batch workflow prerequisites (get_max_batch_size, list_templates) and merge semantics. Missing explicit note on destructiveHint=true/overwrite behavior and plan limit details.

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 schema already documents both parameters in detail. Description reinforces merge behavior and ID resolution which are informative but largely duplicates schema guidance. Baseline 3 is appropriate.

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

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

Specific verb+resource: 'Creates multiple images from one or more saved templates.' Clearly distinguishes from create_templated_image ('Use create_templated_image for a single image') and from create_batch_images, and names it explicitly.

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

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

Explicit when-to-use and alternatives: 'Call get_max_batch_size first', 'resolve unknown IDs with list_templates', 'Use create_templated_image for a single image or inline preview.' Names specific sibling tools and the conditions that select them.

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

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

Annotations already declare the write/side-effect profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description only needs to add context — and it does, disclosing that include_image_data/include_file take longer and that the asset URL remains available if embedded file data fails. It does not explain the destructive/overwrite implications or deduplication behavior, which is the main remaining gap.

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

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

Four sentences, front-loaded with the purpose/alternative routing before the parameter hints, so an agent gets the selection decision first. Minor redundancy with schema text on the selector and preview flags keeps it from 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?

With an output schema present, the description need not explain return values, yet it still names asset ID, URL, and format — leaving little ambiguity for a 3-parameter tool with nested content. The absence of any note on destructive/overwrite semantics is the one meaningful omission.

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

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

Schema description coverage is 100%, so the schema already documents content.selector, include_image_data, and include_file in comparable detail. The description largely restates those descriptions ('Set content.selector to crop to a specific element') rather than adding new semantics, which is the expected baseline when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource ('Creates an image from supplied HTML and CSS') and immediately distinguishes this tool from two named siblings, create_url_image and create_template. An agent can select it without opening any schema.

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

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

It gives explicit routing rules: use this for a single graphic/card/document, use create_url_image for an existing page, use create_template to save a reusable design. It also states the conditions for the optional preview flags ('only when an inline preview is needed').

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write/non-idempotent profile is covered. The description adds real context beyond that: what is returned ('in item, including id ... and domain_id') and the entitlement gate ('Requires a plan that supports OG configurations'). It omits auth specifics and rate limits, so not a full 5.

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

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

Four sentences, no filler, and the core purpose plus the branch-selection rule are front-loaded before the return/entitlement/alternative details. Slightly dense but every sentence carries weight.

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

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

For a complex nested-object creation tool with a declared output schema, the description supplies the mode selection, the plan requirement, the return shape, and the sibling routing. Nothing an agent needs to call it correctly is missing; return values need not be expanded further since an output schema exists.

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% on a single nested content parameter, so the baseline is 3. The description restates the html_css/templated split and the default_options/extract_values relationship, but that guidance is already in the schema's content description, so little new meaning is added.

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

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

States a specific verb and resource ('Saves a new Open Graph image configuration for pages on an HTTPS website') and immediately disambiguates the two config_type branches. An agent can separate this from create_url_image, create_template, and update_og_config without opening any schema.

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

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

Explicitly routes between the two modes ('Use config_type: html_css ... or templated ...') and names the two nearest alternatives with their distinguishing conditions: create_url_image for a single page screenshot, update_og_config to change an existing configuration. Also states the plan prerequisite.

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 behavioral context beyond the annotations by stating that the response includes the proxy ID and configuration but omits passwords. It makes the mutation side effect obvious and provides security-relevant return behavior, though it does not describe error cases or name-conflict handling.

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 concise sentences with no filler. The purpose and the important return behavior are front-loaded, and every clause adds operational 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?

The input schema is complex with nested objectsaging and 100% coverage, and the output schema is noted as present, so the short description is sufficient for invocation. The only real gap is lack of explicit alternative routing, but that is already accounted for in usage_guidelines.

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

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

Schema description coverage is 100%, and every nested property already has detailed meaning in the input schema. The tool description contributes no significant parameter-specific guidance 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 uses a specific verb and resource: it creates an organization proxy for routing image requests registry. This is clearly differentiated from sibling tools like update_proxy, delete_proxy, and get_proxy, and it tells the agent the core return value (ID and config without passwords).

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 verb 'creates' makes the lifecycle intent clear, so an agent can infer this is for new proxies rather than updates or deletes. However, the description never explicitly says to use update_proxy for changes or provides exclusions, leaving alternative routing to inference.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description adds genuinely useful traits beyond that: a side-effect write test before creation, best-effort cleanup ('deleted when possible'), conditional success/failure tied to the disabled flag, and a promise that the response excludes secret access keys. This materially exceeds what annotations alone 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?

Four dense sentences, front-loaded with the primary action. Every sentence earns its place: purpose, cleanup caveat, enable/disable condition, and response-content guarantee. No repetition of 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?

Despite the tool's complexity (7 provider variants, nested required fields, conditional secrets), the description plus a 100%-covered schema and an output schema cover everything an agent needs. Prerequisites like bucket existence and IAM trust policy live in the schema; the description supplies the behavioral glue (test flow, cleanup, conditional failure, no secrets in response).

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

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

Schema description coverage is 100%, so the schema carries parameter documentation, giving a baseline of 3. The description adds only marginal parameter meaning by clarifying the disabled flag's interaction with test results — a nuance the schema partially states ('Enabling requires a successful connection test'). No additional syntax or provider-specific info is needed from the description.

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

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

The description opens with a specific verb and resource — 'Creates a storage destination' — and adds a distinctive behavior (testing a write to the bucket) that sets creation apart from the update/get/delete/list storage-destination siblings. An agent can tell this from create_proxy, create_template, and update_storage_destination without opening the schema.

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

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

The description gives clear conditional guidance: enabled destinations require a successful test while explicitly disabled destinations may be saved with a failed test. It does not explicitly name alternatives such as update_storage_destination for modifying existing destinations, but the create verb and clear context make the intended use evident.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds useful non-annotation context: that new ids/versions are returned and that Handlebars substitution happens in HTML only. It doesn't discuss permissions or quota behavior, but for a non-destructive create the added 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?

Four tight sentences that front-load what the tool does, then the placeholder behavior, return values, and sibling routing. No filler; each 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?

An output schema exists so return values needn't be fully explained, yet the description still names the key returned fields (item.template_id, item.template_version) and the follow-up call, completing the create-then-render workflow. Nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100% and the single nested content object is thoroughly described in the schema itself. The description's mention of Handlebars placeholders and HTML-only evaluation largely restates guidance already present in the css/html field descriptions, so it adds little beyond 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 states a specific verb and resource ('Saves a reusable HTML/CSS image template for rendering multiple images with different values') and explicitly distinguishes itself from create_image (single image) and update_template (revise existing). An agent can identify this as the template-creation tool without opening the schema.

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

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

It gives explicit downstream routing: call create_templated_image with the returned ID and template_values to render, use create_image for a single image, and update_template to revise. Both when-to-use and the alternatives are named.

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

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

Annotations already flag the write behavior (readOnlyHint=false, idempotentHint=true, destructiveHint=true), and the description adds genuine context beyond them: the response carries an asset ID, URL, and format in 'item', include_file embeds the binary as an MCP resource, and include_image_data triggers a slower eager render with progress notifications. It does not explain why destructiveHint is true for an image-creation call, which is the one behavioral note an agent might want.

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?

Four tight sentences, front-loaded with the core action and followed by dependency resolution, option behavior, and a sibling cross-reference. Minor redundancy where it echoes schema text on the 'omit version' default, but no wasted framing or filler.

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

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

For a 5-parameter tool with nested template_values, full schema coverage, an output schema, and rich annotations, the description covers the action, the required inputs, the template-resolution path, and the two eager-render options. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail, including the 10 MiB cap, deferred-render caveat, and version resolution. The description mostly restates this ('Omit version to use the latest version') and adds only a light gloss on template_values. Baseline 3 applies when the schema does the heavy lifting.

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

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

The first sentence names a specific verb and resource ('Creates an image from a saved template') and explains the variable mechanism ('template_values for its variable substitutions'). It separates itself from create_template ('save a new reusable design') and list_templates. It never distinguishes itself from the batch sibling create_batch_templated_images or create_image, which is the one residual 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?

Gives concrete routing advice: use a known template_id directly or call list_templates to resolve a name, and omit version to get the latest. It also tells the agent to use create_template first when the design doesn't exist yet and to enable include_image_data only when an inline preview is needed. No explicit guidance on when to prefer this over the batch variants.

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 openWorldHint=true and destructiveHint=true; the description supplies the reason, namely that it fetches a live page and executes its JavaScript. It also discloses the return payload (asset ID, URL, format in item) and the cost tradeoff of eager rendering for inline data and embedded files. It stops short of noting side effects such as stored assets counting against quota or dedupe behavior, which is why it is not a 5.

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

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

Front-loaded with what the tool does, then capture-mode guidance, then the return shape, then sibling routing. Every sentence carries information, though the return-value sentence overlaps with what the output schema already provides.

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 tool with a deep nested content object, the description covers the essential capture modes, the eager-preview flags, and the correct sibling routing, and an output schema handles return values. It does not mention prerequisites such as proxy or storage destination IDs needing prior resolution, leaving some setup context to the 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?

Schema description coverage is 100%, so nearly every parameter is already documented in the schema; the description mainly adds selection guidance for full_screen, selector, include_image_data, and include_file. It says nothing about the long tail of options (proxy_id, storage_destination_id, pdf_options, jumbo dimensions, request_overrides) that the schema carries alone. With the schema doing the heavy lifting, the baseline of 3 is right.

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

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

States a specific verb and resource ("Creates a screenshot of an existing web page at content.url") and immediately clarifies that rendering loads resources and executes JavaScript. Sibling tools are named later, so an agent can separate this from create_image and create_templated_image without opening a schema.

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

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

Explicitly routes between the three creation tools: this one for existing URLs, create_image when supplying HTML/CSS directly, and create_templated_image for saved templates. It also gives in-tool selection rules (full_screen for the whole scrollable page vs selector for a single element) and when to use include_image_data versus include_file.

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

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

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false) by disclosing that an enabled webhook immediately fires a webhook_test delivery to the external endpoint, that test_event_id identifies it in the result, and that the returned configuration omits secret parameter values and the signing secret. The outbound-network side effect and secret redaction are exactly the kind of behavior an agent must know before invoking a create.

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

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

Three sentences, front-loaded with purpose then constraints then side effect, with no filler. Each clause carries distinct operational information.

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

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

For a nested, single-parameter create tool with a fully documented schema and an output schema, the description supplies the remaining behavioral essentials: authorization prerequisites, the api_key exclusion, the automatic test delivery, and secret redaction in the response. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: api_key events cannot be subscribed through MCP even though they appear in the events enum, and enabling the webhook triggers a test delivery (clarifying the disabled default). It does not touch url, parameters, or signing_enabled semantics, which the schema already covers.

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

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

States a specific verb and resource ("Creates a webhook") plus the scope and target ("sends the selected organization events to an HTTPS endpoint"), which clearly separates it from list_webhooks, get_webhook, update_webhook, and delete_webhook. An agent can pick this tool without opening the schema.

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

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

Provides real eligibility constraints — read access to an event's resource is required to subscribe, and api_key events cannot be subscribed through MCP — which steers event selection. However, it never routes the agent between create/update/delete or says when creating a webhook is the wrong choice over updating an existing one, so the when-to-use-vs-alternative guidance is only implied.

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 annotation set already declares destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds the return behavior 'Returns true on success' and names the resource being destroyed, which is consistent with the annotations but not substantially richer than them.

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 action and then states the return behavior. There is no filler or redundant wording.

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 deletion tool with strong annotations and an output schema, the description is complete. It states what is deleted and what the successful result is, with no missing operational detail.

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 covers the single parameter 'id' with a clear description, reaching 100% coverage. The tool description adds no additional parameter semantics, 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 the specific verb 'Deletes' and identifies the exact resource, 'Open Graph image configuration'. This clearly distinguishes the tool from sibling delete_proxy and delete_storage_destination, as well as from create_og_config, update_og_config, and list_og_configs.

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

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

No guidance is given on when to use this tool versus alternatives such as update_og_config or create_og_config. There is also no mention of prerequisites or side effects beyond the deletion itself, leaving usage context implied rather than explicit.

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

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

The description goes beyond the destructiveHint and idempotentHint annotations by adding concrete behavioral details: repeated deletion succeeds and the tool returns true on success. This gives the agent confidence about idempotent retries and expected return 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 concise and front-loaded, with the core action stated first, followed by the consequence, idempotency note, and return value. Each of the three sentences adds distinct useful information with no filler.

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

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

This is a simple single-parameter deletion tool with rich annotations, full schema coverage, and an output schema. The description covers the outcome, idempotent behavior, and return value, so nothing essential is missing for an agent to invoke it correctly.

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

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

The schema has 100% coverage, with the id parameter already described as 'ID of the proxy to delete.' The description does not add parameter-level detail, but the schema fully documents the only parameter, so baseline 3 is appropriate.

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

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

The description starts with the specific verb 'Deletes' and names the exact resource, an organization's proxy. It also states the purpose ('so it can no longer be used for rendering'), which clearly differentiates this from get, update, and list proxy 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 clearly implies this tool is used when a proxy should be removed and made unusable for rendering. It does not explicitly name alternatives or state when not to use it, but for a straightforward deletion tool the usage context is reasonably evident.

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 indicate destructive and idempotent behavior. The description adds meaningful context beyond this: stored credentials are deleted, the underlying bucket/files are preserved, repeated deletion succeeds, and it returns true on success. This gives the agent a fuller picture of side effects and 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?

Four short sentences, each carrying distinct useful information: what is deleted, what is not deleted, idempotency, and return value. The most important scoping detail is front-loaded, and there is no redundant or filler text.

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 is simple with a single required parameter, annotations cover the safety profile, an output schema exists, and the description covers side effects and success behavior. Nothing critical is missing for an agent to invoke this tool correctly.

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

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

The input schema has 100% description coverage for the single 'id' parameter, and the description does not add parameter-specific meaning. The schema fully documents what the parameter is, so the description adds no additional semantic value 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?

The description uses a specific verb and resource: 'Deletes the storage destination configuration and its stored credentials.' It clearly identifies what is being deleted and distinguishes this from sibling deletion tools like delete_og_config and delete_proxy by naming the storage destination resource.

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 scope boundaries, especially that the bucket and stored files are not deleted, but it does not explicitly state when to choose this tool over alternatives or mention related lifecycle tools like create_storage_destination or update_storage_destination. Usage is implied rather than directly guided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely new behavioral detail beyond that: unsent deliveries are discarded, not delivered, and the return is a bare boolean. That is useful operational context an agent cannot get from annotations alone.

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?

Four short front-loaded sentences, each carrying a distinct fact (action, delivery behavior, idempotency, return value). Slightly redundant since the output schema already defines the return, but the sizing is appropriate and there is no filler.

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

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

For a destructive single-parameter tool with full annotation coverage and an output schema, the description covers the operation, side effects on queued deliveries, retry semantics, and result. Only minor gaps remain, such as authorization requirements or behavior for a nonexistent ID (which 'repeated deletion succeeds' partially implies).

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

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

There is a single parameter with 100% schema description coverage, so the baseline is 3. The description adds no further meaning about the ID (format, source, whether it must be an existing webhook) beyond what the schema states.

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 (deletes) and resource (webhook), making the operation unambiguous and easily separable from siblings like delete_proxy or delete_og_config. It does not explicitly name an alternative, but the resource noun does the differentiation work.

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?

'Repeated deletion succeeds' implicitly signals this is safe to retry and usable in cleanup flows, but there is no explicit statement of when to prefer this over other tools or what prerequisite state (e.g., webhook must belong to the caller's account) is required. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by naming the exact returned values and clarifying that no storage destination ID input is needed. It does not contradict 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 two sentences, front-loads the return values, and immediately follows with actionable usage instructions. Every sentence earns its place with 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?

This is a low-complexity, zero-parameter, read-only tool with an output schema and rich annotations. The description fully covers what is returned and how to apply those values, so nothing needed for correct invocation is missing.

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

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

With zero parameters and 100% schema coverage, the schema leaves little to explain. The description still adds value by explicitly stating 'No storage destination ID is required,' which prevents confusion with sibling tools that do require a destination ID.

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

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

The description states a specific verb and resource: 'Returns the current organization's external_id and HCTI writer_role_arn.' It also distinguishes itself from storage-destination-specific tools by noting 'No storage destination ID is required,' making its 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 gives clear context for when to use this tool: when configuring S3 storage, specifically using external_id as sts:ExternalId and writer_role_arn as Principal.AWS. It does not explicitly name alternative tools or state when not to use it, but the 'No storage destination ID is required' line implies a distinction from get_storage_destination.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description goes beyond these by disclosing the specific return semantics: 'Returns 0 when batching is not supported' and the recommended fallback action. This adds behavioral context that annotations do not 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 a single, efficient sentence with two clauses: the core action and the special-case behavior. No filler, and the most important information (what the tool returns) is front-loaded before the conditional note.

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

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

For a parameterless getter, this is complete. It explains the primary purpose, the semantic meaning of the return value in cases where batching is unsupported, and provides a fallback instruction. The output schema presumably defines the exact response shape, so no further explanation is needed.

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 zero parameters, and schema description coverage is 100% (since there are no params to cover). The description appropriately does not need to add parameter details. Baseline for 0-parameter tools is 4, and nothing here lowers that.

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 ('Get'), a clear resource ('maximum number of images that can be created in a single batch'), and the scoping ('according to the user's plan'). It clearly distinguishes from sibling create_batch_images, which actually creates batches, by focusing on the limit rather than creation.

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

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

It provides actionable guidance for the 0-return case, instructing the agent to 'create images individually instead,' which implicitly tells when to avoid using the batch-creation sibling. It doesn't explicitly name the sibling tool or state 'use this before create_batch_images,' but the conditional fallback is a clear usage signal.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds value by explaining that the read preserves existing settings ahead of a mutation and that returned options are mode-specific, though it says nothing about permissions or rate limits.

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

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

Two tight sentences, front-loaded with the core action and followed immediately by the usage routing. 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?

With an output schema present, the description needn't explain return values, yet it still sketches them; combined with full annotation coverage and a single fully documented parameter, nothing an agent needs to call this correctly is missing.

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

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

Single 'id' parameter with 100% schema description coverage, so the schema already documents it fully. The description adds no format, source, or constraint detail beyond what the schema provides; baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Retrieves one Open Graph image configuration by ID') and even enumerates the returned fields (mode, enabled state, domain_id, rendering options). An agent can distinguish it from list_og_configs and create_og_config without opening any schema.

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

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

Explicitly names two alternatives and the conditions that select them: 'Use this before update_og_config to preserve existing settings; use list_og_configs to discover an ID.' This is exactly the when/when-not guidance the dimension rewards.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond that: it states that the username is returned and passwords are never returned, which is a security-relevant guarantee an agent needs to know.

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

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

Two concise sentences with no redundant content. The core action is front-loaded, and the additional return-value detail is both relevant and necessary.

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 single required parameter, an output schema, and annotations covering read-only and idempotent behavior. The description fills the remaining gap by specifying return details, especially the password-never-returned guarantee, making it complete for safe invocation.

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

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

Schema description coverage is 100% and the only parameter 'id' is already documented as 'ID of the proxy to retrieve.' The description does not add extra parameter-level detail, so the baseline of 3 applies.

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

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

The description states a specific verb ('Gets') and resource ('organization's proxy configuration'), and clarifies what is included (enabled status, authentication configuration). This distinguishes it from sibling tools like create_proxy, update_proxy, and list_proxies.

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

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

The description implies the tool is for retrieving a single proxy configuration by ID, but it does not explicitly say when to prefer this over list_proxies or other related tools. Usage context is clear but not stated as explicit guidance with alternatives or exclusions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations by explicitly stating that secret access keys are never returned, which is important behavioral information for an agent.

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 concise sentences that front-load the core purpose and add a valuable security-relevant note. Every sentence contributes information without 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 low-complexity, single-parameter read tool with full schema coverage, rich annotations, and an output schema, the description is complete. It clearly states what is retrieved and the key non-returned value, leaving no significant gaps for correct invocation.

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

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

Schema description coverage is 100%: the single 'id' parameter is documented as 'ID of the storage destination to retrieve.' The description does not add parameter-specific detail, but the schema is sufficient, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Gets') and a specific resource ('a storage destination's configuration, enabled state, and most recent connection test result'). It clearly distinguishes from list_storage_destinations by focusing on a single destination and its detailed settings, and adds a differentiating security detail about secret access keys.

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 when to use the tool: when an agent needs a single storage destination's configuration, enabled state, or connection test result. However, it does not explicitly mention alternatives such as list_storage_destinations or state conditions for choosing this tool over siblings.

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

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

Annotations already establish readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine value beyond that by disclosing a redaction rule: secret parameter values and the signing secret are never returned, which tells the agent not to expect full configuration even in the returned object. It stops short of noting error behavior for an unknown ID.

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

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

Two tight sentences with zero filler; the scope-defining first sentence comes first and the caveat about redacted secrets follows immediately. Every clause carries information an agent can act on.

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?

An output schema exists, so the description needn't detail return fields, and it still summarizes them at a useful altitude; the redaction note closes the main expectation gap. The only remaining omission is how an agent obtains a valid webhook ID, which is minor for a one-parameter read 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?

With a single parameter at 100% schema description coverage, the schema already fully documents the required 'id' string. The description adds no format hints, no explanation of where the ID comes from, and nothing beyond what the structured field provides, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Gets a webhook') and enumerates exactly what comes back: endpoint, subscribed events, parameters, signing setting, enabled state. It does not, however, distinguish itself from near-neighbors like get_webhook_event or list_webhooks, so an agent must infer the boundary from the name alone.

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

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

Usage is only implied by the 'get' verb plus the 'ID of the webhook to retrieve' parameter — clearly a single-record lookup by ID. There is no explicit when-to-use versus list_webhooks (to discover IDs) or get_webhook_event (for event payloads), and no statement of prerequisites such as needing an existing webhook ID.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description still earns credit by disclosing a non-obvious degraded state — data comes back null and payload_withheld is true when the caller lacks read access to the event's resource — which is exactly the kind of authorization-driven behavior an agent cannot get from 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 sentences, no filler. The returned-content summary leads and the edge-case state follows, so the most decision-relevant information is front-loaded.

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

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

An output schema exists, so return-value documentation is not strictly required, and the description still sketches the response shape and the withheld-payload case. What's missing is the relationship to sibling webhook tools, which is the only real gap for a one-parameter read 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?

Single required parameter with 100% schema coverage, and the schema already gives examples (test_event_id, event_id). The description adds no further meaning about event_id, so the baseline 3 applies rather than a higher score.

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

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

States a specific verb and resource ('Gets one webhook event') and enumerates what comes back: the payload plus each destination's delivery status and HTTP attempts. That distinguishes it from get_webhook (the webhook config) in substance, but the description never names that sibling explicitly, leaving the agent to infer the split from the resource noun alone.

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?

There is no statement of when to reach for this tool versus get_webhook, list_webhooks, or send_webhook_test_event. The only conditional clause ('when you can't read the event's resource') describes a runtime state, not a selection criterion, so routing must be inferred entirely from the tool name.

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

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

Annotations already establish the safe read profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description still adds real behavior: descending creation ordering, inclusion of disabled configurations, and the null-cursor terminator for pagination.

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

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

Three short sentences, all front-loaded with the highest-value facts first (scope/ordering, then pagination mechanics). No filler or restated name text.

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?

An output schema exists, so return shape need not be described; nonetheless the description names item.data and item.pagination.next_page_start, giving the agent enough to iterate pages correctly. Ordering, membership, and pagination are all covered for a two-parameter list tool.

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

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

Schema coverage is 100%, so baseline is 3, and the schema already documents count and page_start. The description goes further by explaining the cursor's origin (item.pagination.next_page_start) and the terminal condition (null cursor), which adds operational meaning for page_start.

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

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

The description states a specific verb and resource ('Lists the organization's Open Graph configurations') and adds scope detail (descending creation order, includes disabled configs). It does not explicitly contrast itself with get_og_config, but the list-vs-get distinction is unambiguous given the resource is named.

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

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

Usage is implied rather than stated: this is the way to enumerate all OG configs (including disabled ones) when you don't have a specific ID. No explicit when-not or named alternative such as get_og_config is offered, leaving the choice to inference from the tool name.

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 say read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: it includes disabled proxies by default, hides passwords in item.data, and explains pagination continuation with next_page_start and null cursor as the terminal marker. This gives an agent important operational expectations without contradicting 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 compact and efficient: three sentences cover scope, security-sensitive return content, downstream use of IDs, and pagination. Every sentence earns its place and the most important information is front-loaded.

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

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

The tool is simple: two optional parameters, full schema coverage, a rich output schema, and annotations covering safety. The description fills the remaining gaps with pagination behavior, the password-exclusion guarantee, and how IDs should be used downstream. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents count and page_start clearly. The description reinforces how page_start relates to item.pagination.next_page_start and when pagination ends, but it does not add substantial semantic meaning beyond what the input schema already states.

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

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

States a specific verb and resource ('Lists the organization's proxies') and adds important scope detail ('including disabled proxies'), which distinguishes the list operation from get_proxy and the create/update/delete siblings. The downstream instruction about using an id as proxy_id further clarifies what the listed items are for.

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 context for when to use this tool: to list all proxies, including disabled ones, and to obtain IDs for image or template requests. It does not explicitly name an alternative such as get_proxy for single-item lookups, but the purpose and pagination flow make the usage context reasonably clear.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behaviors: disabled destinations are included, secret access keys are omitted from item.data, and pagination works via next_page_start with a null cursor marking the end. These are non-obvious traits that materially affect how an agent consumes the 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?

Four sentences, each earning its place: purpose, security behavior, downstream usage of ids, and pagination. The most important scoping detail ('including disabled destinations') is front-loaded, and there is no repetition of schema or annotation information.

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

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

With an output schema present, an explicit pagination contract, and annotation-provided safety profile, the description covers everything needed to invoke the tool correctly. The two optional parameters are fully documented in the schema, and the description clarifies the pagination flow and secret handling.

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 adds a small nuance by stating that a null cursor marks the last page, reinforcing the schema's pagination guidance, but it does not meaningfully extend parameter meaning beyond what the schema already documents.

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

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

The description uses a specific verb ('Lists') and resource ('storage destinations'), with a clear scope ('the organization's') and an important differentiator ('including disabled destinations'). This cleanly distinguishes it from sibling tools like get_storage_destination, create_storage_destination, and the list tools for other resources.

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 makes the list operation's purpose obvious and adds context about including disabled destinations, which implies when this is the right tool. It also tells how to use returned ids in image or template requests. However, it does not explicitly contrast with alternatives like get_storage_destination for a single destination, so it stops short of a fully explicit when/when-not statement.

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 openWorldHint=false, so safety is covered. The description adds genuine behavioral detail beyond them: results live under data, ordering is newest-first, and pagination terminates when data is empty or the cursor is null. It does not discuss rate limits or result-size shaping, hence a 4.

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?

Four short sentences, front-loaded with purpose, then usage, then chaining, then pagination. Every sentence carries actionable information with no filler.

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

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

An output schema exists, so return values need not be re-explained, and the description still points the agent to the data field and the cursor. For a two-parameter read-only list tool, this covers everything needed to call it correctly and chain it into create_templated_image.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly further by framing max_version as a continuation cursor tied to pagination.next_page_start and by stating when to stop, which clarifies the otherwise counterintuitive 'version' naming better than the schema alone. It does not explain the count upper bound, which the schema already covers.

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

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

States a specific verb and resource ('Lists the connected organization's templates') and adds scope ('with their latest versions, newest first'), which implicitly separates it from the sibling list_template_versions that returns full version history. An agent can identify this as the template-discovery tool without opening the schema.

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

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

Gives an explicit use case ('find a template by name and inspect its content and rendering settings') plus the next-step routing: pass an entry's id as template_id to create_templated_image. It also spells out the pagination loop and its stop condition, leaving nothing to inference.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: newest-first ordering, that versions are returned inside `data`, and the exact cursor-continuation rule (`pagination.next_page_start` → `max_version`, stop when data is empty or cursor is null). That is well beyond what the annotations convey.

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

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

Three compact sentences: what it returns, when to use it, and how to paginate. Front-loaded with the purpose and free of redundant restatement of the schema.

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

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

For a read-only, three-parameter paged list with an output schema, nothing an agent needs is missing — return envelope, ordering, and the full pagination protocol are all covered.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description still adds value by framing `max_version` as a continuation cursor fed from the prior response and by describing the termination condition, clarifying the cross-field pagination relationship rather than restating types.

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

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

States a specific verb and resource (list saved versions of one template), the ordering (newest first), and what each entry contains (content and rendering settings). It is clearly distinguishable from list_templates, which lists templates rather than their versions.

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

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

Explicitly names two use cases — inspecting a template before update_template and picking an older version for create_templated_image — and then explains the pagination loop with an explicit stop condition. Alternatives and continuation behavior are both spelled out rather than inferred.

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

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

Beyond the readOnly/idempotent annotations, the description discloses three things annotations cannot: disabled webhooks are included in results, secret parameter values and signing secrets are redacted from the response, and pagination is cursor-based with a null cursor marking the final page. Those are exactly the behavioral facts an agent needs before trusting or looping on the output.

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

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

Two sentences, front-loaded with what is listed and scoped, then response-shape and redaction facts, then pagination. No filler, and each clause carries distinct information.

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

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

For a two-parameter, annotation-covered read tool with an output schema, this description covers scope, redaction, and pagination termination—everything needed to call it correctly and to stop looping at the right time.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the operational link between the cursor it returns (item.pagination.next_page_start) and the page_start input, telling the agent to pass it back verbatim—slightly more than the schema's per-field wording conveys on its own.

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

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

States a specific verb and resource ('Lists the organization's webhooks') and immediately scopes it with 'including disabled webhooks', which distinguishes it from get_webhook and from the other list_* siblings operating on proxies, templates, and storage destinations.

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

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

Usage is implied rather than stated: an agent can infer this is the enumeration counterpart to get_webhook, but the description never says when to prefer it over get_webhook or over the sibling list_* tools, and names no exclusions or prerequisites.

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 annotations, the description discloses key behavior: deliveries are signed and carry the same parameters as real deliveries, each webhook is rate-limited to one test every 30 seconds, and the tool returns an event ID. This gives an agent substantial operational context.

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 tightly written sentences, front-loaded with the action and followed by rate-limit and return/status guidance. No sentence is redundant.

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

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

Given the annotations, one fully documented parameter, and the presence of an output schema, the description supplies all remaining context an agent needs: what is sent, how it is signed, the rate limit, and how to check delivery status.

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% for the single webhook_id parameter, so the schema already explains the parameter. The description adds only that the target webhook must be enabled and that its endpoint receives the delivery, which is useful but modest beyond the schema.

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

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

The description states a specific verb and resource: sending a webhook_test delivery to an enabled webhook's endpoint. It distinguishes the test event from normal deliveries and names the sibling get_webhook_event for checking 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?

It clearly indicates this is for test deliveries and points to get_webhook_event for status checks. It could more explicitly say when to use this versus other webhook tools or when not to use it, but the test-event context is clear.

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

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

Annotations cover the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description's job is to add what they don't say. It does: the consent gate before submission, the privacy prohibition on secrets/PII, and that a confirmation message plus feedback ID is returned. It stops short of describing delivery guarantees or rate limits, but the added context is substantive.

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

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

Front-loads what the tool does and what it is for, then layers on consent and privacy constraints. Four sentences with essentially no filler, though the closing sentence about the return value is largely redundant given the output schema exists.

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 is simple (one required string parameter), annotations carry the safety profile, an output schema exists, and the description still supplies the two things an agent could get wrong: consent before sending and excluding confidential data. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters (message, subject, callback_url) are already documented, including the 20-character minimum and the null defaults. The description's 'what you tried, what you expected, what happened' phrasing reinforces the message parameter but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Sends) and resource (feedback to the HCTI team) and enumerates the subject matter it covers: the product, its API, and its MCP tools. No sibling tool does anything similar, so the agent can immediately place it among the create_*/update_*/list_* CRUD tools without 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?

Explicitly enumerates when to use it (bugs, unexpected rendering results, feature requests, confusing behavior or docs, improvement suggestions) and adds a hard precondition: 'If the user did not ask you to send feedback, ask them before submitting.' It also gives an exclusion on content (no API keys, credentials, tokens, or personal/confidential data), which is actionable when/when-not guidance rather than implied usage.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes further and explains exactly what the destruction looks like: omitted optional settings are cleared or reset to defaults, and only disabling is accepted after a plan downgrade (other changes silently ignored). It also discloses downstream impact on subsequent image requests and the response location, none of which the annotations carry.

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

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

Five short sentences, purpose and replacement semantics front-loaded, then prerequisites, then edge cases. No sentence is redundant against the schema or the annotations; the plan-downgrade caveat earns its place by preventing failed partial updates.

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 deeply nested, config_type-discriminated payload with an output schema present, the description supplies everything structured data cannot: full-replacement semantics, the preserve-via-get_og_config workflow, and plan-gated degradation. Return values are already covered by the output schema, so nothing needed is missing.

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

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

With 100% schema description coverage the baseline is 3, but the description adds real semantics beyond the schema: content is a full replacement rather than a patch, it must match the chosen config_type, and the enabled/disabled inversion is called out. It does not elaborate per-field defaults, which the schema already covers well.

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

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

States a precise verb and resource ('Replaces an existing Open Graph image configuration') plus the return contract ('returns the saved configuration in item'). The word 'Replaces' immediately separates it from the sibling create_og_config, which builds a new one, so an agent can route correctly without opening a schema.

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

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

Gives a concrete prerequisite ('Call get_og_config first to inspect settings that should be preserved'), the replacement discipline ('Supply the complete configuration for the chosen config_type'), and a plan-gated edge case where only disabling is honored. It names no alternative update path or when-not-to-use sibling, so it stops one step short of full routing 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?

Beyond the annotations, it discloses the destructive full-replacement behavior, explains that omitted optional settings including authentication are cleared, and captures the non-obvious retain_password rule. It also tells the agent that returned configuration excludes passwords. This is precisely the kind of behavioral context that reduces mis-invocation.

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

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

Three short sentences and no filler. The full-replacement behavior is front-loaded, followed by the critical edge cases, and then the output behavior. 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?

Given the rich nested schema, existing annotations, and output schema, the description covers the important nuances: overwrite semantics, clearing of omitted values, password retention requirements, and password redaction. Nothing substantial that an agent needs in order to call the tool correctly is missing.

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

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

The schema already provides 100% parameter coverage with detailed descriptions, so the description gets no credit merely for repeating those fields. However, it does add cross-cutting meaning by stating that omitted optional settings are cleared and by summarizing the authentication retention rule, which is useful before an agent reads through the nested schema.

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

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

The description states a specific verb and resource: it replaces the complete proxy configuration. The phrase 'complete proxy configuration' clearly distinguishes it from create_proxy, delete_proxy, or get_proxy, so an agent can identify the right tool without opening the schema.

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

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

The description makes clear that this is for full replacement of an existing proxy and flags the most important consequence: omitted optional settings are cleared. It does not explicitly name create_proxy or delete_proxy as alternatives, but the update-versus-create distinction is contextually clear enough for an agent to route between them.

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

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

Discloses non-obvious behaviors well beyond the annotations: omitted settings are cleared or reset, secret retention requires retain_secret_access_key: true with unchanged provider and key ID, changed connections and re-enabling trigger a bucket write test, failed tests prevent saving an enabled request, and plan downgrades restrict changes to disabling only. This complements rather than contradicts destructiveHint: true.

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

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

Five sentences with zero filler: purpose is front-loaded first, followed by the clearing/secret caveat, the write-test side effect, the failure behavior, and the plan restriction. Every sentence earns its place and no information is repeated from the schema.

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

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

For a complex mutation tool with nested objects, seven provider variants, secret-handling rules, test side effects, and plan constraints, the description addresses every non-obvious behavioral aspect an agent needs. Combined with 100% schema coverage and an output schema, nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds the global rule that omitted optional settings are cleared or reset, and highlights retain_secret_access_key's interaction with provider and access-key changes — cross-object semantics that the individual schema property descriptions do not convey.

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

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

Opens with a specific verb-resource pair: 'Replaces a storage destination's configuration.' This clearly distinguishes it from the close siblings create_storage_destination, delete_storage_destination, get_storage_destination, and list_storage_destinations. The replacement semantics are unambiguous.

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

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

The replace semantics and required id parameter make clear this tool modifies existing destinations, and the plan-downgrade note adds useful conditional context. However, it never explicitly names create_storage_destination as the alternative for new destinations, so it provides clear context without stated exclusions.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description complements this by disclosing exactly what gets destroyed and under what condition ('replaces its latest version when that version has not been rendered; otherwise creates a new version'). This is precisely the behavioral nuance the annotations cannot convey.

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

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

Four tight sentences, each load-bearing: identity, replacement semantics, return values, and the two sibling follow-ups. The most important fact (version replacement) is front-loaded right after the opening clause.

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?

An output schema exists, yet the brief return-value summary (item.template_id / item.template_version) is useful for chaining into the render call. Combined with the versioning rules and sibling routing, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the nested content object is documented in exhaustive detail, so the schema does the heavy lifting. The description adds no meaning about content or template_id beyond what is already structured, so the baseline 3 applies.

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

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

States a specific verb and resource ('Updates an existing HTML/CSS image template') and immediately distinguishes its behavior from create_template/create_templated_image by describing the version-replacement semantics. An agent can tell it apart from its siblings without opening a schema.

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

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

Explicitly routes the agent: use list_template_versions to inspect content before replacing it, and call create_templated_image with the returned ID/version to render. It also states the condition under which replacement happens versus a new version being created, which is the key decision an agent must make.

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

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

Annotations already flag destructive, non-idempotent, open-world behavior, but the description adds real substance beyond them: omitted parameters are deleted, secret values must be resent unless retain_value is used (and cannot be kept when the URL changes), mutating calls emit a webhook_test delivery identified by test_event_id, and concurrent modification fails with a conflict. These are the non-obvious side effects an agent would otherwise discover only by breaking a webhook.

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

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

Five dense sentences, front-loaded with the replacement semantics that matter most, and no filler. The permissions sentence is long and packs several conditions together, mildly reducing scannability, but every clause carries information.

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

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

For a destructive, nested-object mutation with 100% schema coverage and an output schema, the description covers the remaining agent-relevant gaps: permissions per change class, secret retention rules, the test-delivery side effect, and the conflict/retry path. Nothing needed to call this safely is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns upward credit by summarizing cross-parameter rules — resend secret values versus retain_value: true, and the URL-change exception that invalidates retention — in a single place rather than leaving the agent to synthesize nested field descriptions. It still defers most detail (limits, reserved header names) to the schema.

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

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

Opens with a precise verb and resource — 'Replaces a webhook's configuration' — and immediately qualifies it with replacement semantics ('Omitted parameters are removed'), which distinguishes it from create_webhook and from a partial-patch tool. An agent can identify the operation without touching the schema.

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

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

Gives concrete decision conditions: which field changes require read access to every subscribed event and trigger a webhook_test delivery, versus which changes only need webhook management access, plus retry guidance after a conflict. It does not name sibling tools (e.g. send_webhook_test_event, get_webhook) as alternatives, so it stops short of explicit routing.

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