app_asset_library_images_update_instance

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

No annotations are provided, so the description carries the full behavioral burden. PATCH implies a partial mutation, which is the only behavioral signal present; nothing is said about required permissions, which fields are mutable, side effects on placements, or what the response contains.

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?

It is short, but the sentence does not front-load purpose; it opens with an HTTP path and then redundantly restates that same path in parentheses. Half the content is duplicated text rather than 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 mutation tool with no annotations and no output schema, the description should at minimum say what is being updated and what the JSON:API envelope requires. Instead it defers entirely to an external OpenAPI component the agent may not have access to, leaving the tool under-specified.

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 both id and body, and the baseline is 3. The description's pointer to components.schemas.AppAssetLibraryImageUpdateRequest is marginally useful for locating the body shape, but it adds no concrete parameter meaning 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 exposes the HTTP verb and resource path (PATCH /v1/appAssetLibraryImages/{id}), from which an agent can infer 'update an app asset library image'. However, the parenthetical repeats the path verbatim instead of describing the effect, and it does nothing to distinguish this from the sibling create/get/delete variants for the same 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?

There is no when-to-use, when-not-to-use, or prerequisite information whatsoever. The agent is given a raw endpoint string and a pointer to an OpenAPI component with no guidance on when this tool is the right choice over app_asset_library_images_create_instance or the get/delete siblings.

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