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 destructiveHint=true and idempotentHint=false, so the description does not need to restate the mutating nature. The description adds useful operational context beyond annotations: the batch plan limit precondition, the zero-limit fallback to individual calls, and the per-image output shape (IDs, URLs, format in item). No contradiction with annotations.

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

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

Three sentences cover purpose, precondition, alternative tooling, and return information without filler. The core function is front-loaded, and 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?

Given the rich schema, output schema, and annotations, the description covers the essential operational guidance: call get_max_batch_size first, respect the limit, fall back to individual calls when needed, and expect per-image IDs/URLs/format. It could name the specific individual creation tools, but the generic reference combined with the sibling list is sufficient for an agent to route correctly.

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

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

Schema description coverage is 100%, so each parameter and nested property is already thoroughly documented. The description adds the high-level relationship that variations override default_options, but this largely summarizes what the schema already states. Baseline 3 is appropriate because no genuinely new parameter semantics are introduced.

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

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

Description states a clear verb-resource pair ('Creates multiple image assets') and explains the batch structure of shared defaults plus per-item variations. It also contrasts with 'individual creation tools' in the final sentence, letting an agent distinguish it from create_image, create_url_image, and create_templated_image.

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 instructs callers to invoke get_max_batch_size first and stay within the returned plan limit, including the edge case where a limit of 0 forces individual image calls. It also states when to use individual creation tools instead: when only one image or 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 signal a non-read-only, potentially destructive operation, so the bar for behavioral disclosure is lower. The description adds useful context about return values (asset ID, URL, format in item) and the performance tradeoff of include_image_data. It does not detail all side effects, but it goes beyond a bare 'creates an image' statement.

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 with no filler. The core action and alternative selection are front-loaded, followed by targeted usage notes.

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 creation tool with a rich nested schema, the description tells the agent what to use it for, how to differentiate it from siblings, how to crop, and what the response contains. Nothing essential for invoking 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 carries the full parameter documentation burden. The description adds no fundamentally new parameter semantics beyond highlighting content.selector for cropping and include_image_data's conditional use, which is helpful but not additional meaning.

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

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

The description opens with a specific verb and resource: 'Creates an image from supplied HTML and CSS.' It also differentiates from siblings by naming create_url_image and create_template, so an agent can distinguish the tools without inspecting schemas.

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

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

It gives explicit selection criteria: use this tool for a single graphic, card, or document; use create_url_image for existing web pages; and use create_template for reusable designs. It also flags include_image_data as only for inline-preview needs, providing clear when-to-use guidance.

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

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

Annotations only convey that this is a mutating, non-idempotent operation. The description adds useful operational context beyond that: the plan requirement and the fact that the saved configuration is returned with id and domain_id. It does not describe every side effect, but the annotations plus description cover the important behavioral expectations.

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 carry the core purpose, mode selection, return info, prerequisite, and sibling alternatives with no filler. The main action is front-loaded and 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?

For a tool with this much schema complexity, the description covers everything an agent needs to choose and invoke it: what it creates, when to use each config_type, the plan prerequisite, return identifiers, and related tools. The exhaustive input and output schemas cover the remaining constraints, so nothing essential 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?

Input schema coverage is 100% and the content property already documents both config_type branches in detail. The description rephrases the html_css vs. templated choice in plain language, which is helpful, but it adds little meaning beyond what the schema already provides, 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 clear verb and resource: 'Saves a new Open Graph (social preview) image configuration'. It also names the two config_type modes and explicitly distinguishes itself from create_url_image and update_og_config, so an agent can tell it apart from siblings without opening schemas.

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

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

It provides explicit selection criteria: use config_type html_css for source pages with default rendering options, or templated for existing templates with metadata extraction. It also names alternatives for nearby tasks, such as create_url_image for single-page screenshots and update_og_config for modifications, and notes the plan requirement.

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?

The description adds meaningful behavioral details beyond annotations: Handlebars substitutions are evaluated in HTML only, and the operation returns item.template_id and item.template_version. It also conveys the persistent side effect of saving a reusable template. No contradictions with annotations.

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

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

Four sentences, each with a distinct job: state the resource and purpose, explain the placeholder mechanism, report return values, and route to alternatives. Every sentence earns its place 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?

The description covers the full create-then-render workflow, names the key return fields, and references the relevant sibling tools. Given the 100% schema coverage and the presence of an output schema, nothing needed for a correct call 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 parameter-relevant meaning by explaining the core placeholder mechanism ('Put Handlebars placeholders such as {{title}} in the HTML') and the HTML-only evaluation constraint. It also links the returned template_id to template_values usage in create_templated_image.

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 object: 'Saves a reusable HTML/CSS image template for rendering multiple images with different values.' It identifies the exact resource and purpose, and distinguishes itself from siblings by naming create_image, create_templated_image, and update_template.

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

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

It explicitly tells the agent when to use this tool versus alternatives: 'Call create_templated_image with that ID and template_values to render an image. Use create_image for a single image from supplied HTML/CSS, or update_template to revise an existing template.' This is clear, direct routing guidance with named alternatives.

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

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

Adds value beyond annotations by explaining what is returned (asset ID, URL, format information in item) and what include_image_data does. Annotations already flag destructiveHint and readOnlyHint, so the description does not need to repeat those. It does not expand on state-changing side effects, but the annotation covers that.

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 with no filler; the main action and key workflow guidance are front-loaded. Each sentence contributes either to understanding the tool or to selecting the right template/version path. It is concise while remaining informative.

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 description is complete for a tool with a rich input schema and output schema. It covers how to find a template, how to choose a version, what the response contains, and when to use create_template. No critical behavioral or workflow information 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%, with detailed parameter descriptions already present. The tool description paraphrases some parameter behavior ('Omit version to use the latest version', 'include_image_data requests an inline preview') but adds little new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Creates an image from a saved template using template_values for its variable substitutions.' This clearly distinguishes it from generic create_image and ties it to templates. The mention of list_templates and create_template further clarifies its role among sibling tools.

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

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

Provides clear operational guidance: use a known template_id, resolve unknown names via list_templates, omit version for latest, and use create_template to save a reusable design before rendering. It does not explicitly say when NOT to use this tool versus create_image or create_batch_images, so it stops short of a full 5.

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

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

Beyond the annotations, the description discloses that rendering loads the page and resources in a browser and executes JavaScript, which is important behavioral context. It also says the call returns asset ID, URL, and format info, and that include_image_data requests an eager inline preview. It does not explain the destructiveHint annotation, but the description still covers the main behavioral surface.

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 front-loaded: the core purpose comes first, followed by the most decision-relevant details and sibling alternatives. Every sentence contributes useful information without repetition 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?

The definition is complete for a correct call: the input schema is fully documented, an output schema exists, and the description adds rendering behavior, return-payload expectations, and sibling routing. An agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents every parameter. The description adds modest value by highlighting content.url, content.full_screen, content.selector, and include_image_data, but it does not need to compensate for any schema gaps.

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 action and resource: 'Creates a screenshot of an existing web page at content.url.' It also differentiates the tool from siblings by naming create_image and create_templated_image, making the tool's exact role unambiguous.

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

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

The description explicitly says when to use create_image for HTML/CSS input and create_templated_image for saved templates, which is direct alternative routing. It also gives actionable selection guidance for full_screen, selector, and include_image_data.

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

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

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 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return payload shape (mode, enabled state, domain_id, mode-specific options/template settings in item). No contradiction with annotations.

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

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

Three sentences, each earning its place: the core action, the return contents, and the routing guidance. The most decision-relevant information (what it does) is front-loaded, 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 format is already structured and need not be re-explained. Annotations cover the safety profile, the single parameter is fully documented, and the sibling-routing guidance completes the picture. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, with the sole parameter fully documented as 'ID of the OG configuration.' The description only confirms the ID is the lookup key ('by ID'), adding no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Retrieves'), a precise resource ('one Open Graph image configuration'), and the scoping mechanism ('by ID'). This clearly distinguishes it from the sibling getters/lists in the toolset, and it is far from a tautology of the title.

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 before update_og_config to preserve existing settings, and use list_og_configs to discover an ID. This routes the agent to the correct tool with zero inference required.

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

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

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 mark this as read-only, idempotent, and non-destructive, so the description wisely adds non-redundant behavior: ordering, inclusion of disabled entries, result location in item.data, and pagination semantics. No contradiction exists between the description and 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?

Three sentences with no filler: the first states what the tool does, the second tells where results live, and the third explains pagination. 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?

For a read-only, paginated listing tool with a rich output schema and annotations covering safety, the description covers the key operational facets: ordering, inclusion, result location, continuation, and terminal condition. Nothing an agent needs to invoke or paginate 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 documents count and page_start at 100% coverage, so the baseline is 3. The description adds operational value by clarifying how to chain pagination ('Pass item.pagination.next_page_start as page_start') and when to stop ('a null cursor marks the last page'), which goes slightly 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?

States a specific verb and resource ('Lists the organization's Open Graph configurations') plus two scoping details that help distinguish it from other config tools: descending creation order and inclusion of disabled configurations. The sibling set includes create/get/update/delete_og_config, and this description makes the list operation unambiguous.

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

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

The description clearly implies use when an agent needs a paginated, organization-wide list of OG configurations. However, it does not explicitly mention alternatives such as get_og_config for a single configuration or state when not to use this tool, so the decision is left to inference.

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

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

Annotations already 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?

The description goes well beyond the readOnlyHint annotation by revealing result ordering, the data field location, pagination cursor mechanics, and the stopping condition ('Stop when data is empty or the cursor is null'). These are actionable behavioral details not present in the annotations.

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

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

Four dense sentences, each carrying distinct information: purpose, workflow, pagination, and termination. Nothing is redundant or wasted.

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

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

For a two-parameter read-only list tool with an output schema and annotations already covering safety, this description is complete. It includes page size guidance in the schema, cursor usage, and a stop condition, so an agent has everything needed to invoke and paginate correctly.

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

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

Schema coverage is 100%, so the schema already documents count and max_version. The description reinforces the cursor pattern ('pass pagination.next_page_start as max_version') but adds no new parameter-level meaning 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 opens with a specific verb and resource: 'Lists the connected organization's templates with their latest versions, newest first.' It further clarifies the tool's role by stating it is for finding a template by name and inspecting content and rendering settings, distinguishing it from siblings like list_template_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?

It gives clear context for use: 'Use this to find a template by name and inspect its content and rendering settings,' and explains how results feed into create_templated_image. It does not explicitly name alternative tools or state when not to use it, but the intended workflow 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?

The description discloses useful behavioral details beyond the read-only annotation: newest-first ordering, inclusion of content and rendering settings, and the full pagination pattern including how to continue and when to stop. This gives the agent a complete operational picture.

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 carry all essential information with no filler. The primary purpose is front-loaded, followed by targeted usage and pagination guidance. 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 read-only annotation, fully described input schema, and presence of an output schema, the description covers everything an agent needs: scope, ordering, content, use cases, and pagination loop. Nothing critical is missing 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%, so the schema already documents all parameters. The description reinforces cursor usage for max_version but mostly repeats what the schema says, adding only a minor stop-condition detail. This is baseline value for a fully covered 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 uses a specific verb and resource: it lists saved versions of one template, newest first, with content and rendering settings. Scoping to 'one template' clearly distinguishes it from sibling list_templates, and the stated use cases help an agent understand its purpose immediately.

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 the tool: inspect a template before updating it or select an older version for create_templated_image. It does not explicitly name alternatives or say when not to use it, so it falls short of full exclusions but provides clear context.

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

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

Beyond the annotations' destructiveHint and readOnlyHint, the description discloses that omitted optional settings are cleared or reset to defaults, changes affect subsequent image requests, and after a plan downgrade only disabling is accepted. These are important non-obvious behaviors that materially affect how an agent should invoke the tool.

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

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

Five sentences, each earning its place: replacement behavior, return value, preservation workflow, clearing semantics, effect timing, and plan-downgrade exception. The most important information is front-loaded, and there is no filler or redundancy.

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

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

For a complex update tool with nested content, the description covers the essential operational context: read before updating, full replacement semantics, clearing behavior, propagation to image requests, and the downgrade edge case. The output schema and annotations cover the remaining details, so nothing critical 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 both parameters thoroughly. The description adds meaningful operational guidance beyond the schema: inspect get_og_config first, omitted optional settings are cleared, and the full configuration must be supplied. This goes beyond the baseline but mostly reinforces and clarifies what the schema already implies.

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 'Replaces an existing Open Graph image configuration,' which is specific about the verb and resource. It clearly distinguishes this from sibling tools like create_og_config by emphasizing 'existing' and replacement semantics, and it adds the return behavior ('returns the saved configuration in item').

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 concrete procedural guidance: call get_og_config first, preserve settings, and supply the complete configuration. It also warns about the plan-downgrade restriction. It does not explicitly name create_og_config as the alternative for new configurations, but the 'existing' framing makes the intended context 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, 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 already mark this as destructiveHint=true.icon, so the description does not need to restate that it modifies state. It adds valuable context beyond annotations: the conditional replace-versus-new-version behavior and the returned item.template_id and item.template_version identifiers. This gives the agent a meaningful model of what happens on 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?

The description is compact and each sentence earns its place: purpose, versioning behavior, return values, next step, and prerequisite inspection. It is front-loaded with the core action and avoids redundancy with the schema or annotations.

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

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

For a destructive update tool with a rich input schema, this description covers the essential behavioral nuance (version replacement/creation), the return values, the required follow-up call, and the recommended pre-inspection step. The output schema and annotations handle the remaining formal details, leaving no critical gap for an agent deciding how to call the tool.

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

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

The input schema is fully documented with detailed parameter descriptions, including nested content fields-based coverage. The description itself adds little parameter-level meaning, but with schema coverage at 100%, the baseline of 3 is appropriate. The 'Returns item.template_id and item.template_version' line helps the agent understand outputs rather than parameters.

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

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

The description opens with a specific verb and resource: 'Updates an existing HTML/CSS image template.' It then explains the versioning behavior (replace unrendered latest version, otherwise create a new version), which distinguishes it from create_template and create_templated_image. The purpose is unambiguous and clearly differentiated from siblings.

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

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

The description gives actionable workflow guidance: use list_template_versions to inspect existing content before replacing, and call create_templated_image with the returned ID/version to render. It does not explicitly contrast with create_template for new templates, but the 'existing' wording and versioning logic make the intended use clear.

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