Update set retrieve

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

Annotations already supply readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is largely covered. The description adds real value beyond that by documenting the cleanup_retrieved side effect (removing the existing retrieved update set), the auto_preview behavior, the returned progress model, and a MissingParameterError on update_set_id — none of which the annotations disclose. It does not, however, reconcile its 'remove the existing retrieved update set' language with destructiveHint=false, nor explain idempotency or remote-side effects.

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 front-loaded with the purpose sentence and organized into param/return/raises sections, which is easy to scan. The cost is boilerplate: every ':type:' line merely restates the JSON schema types, and the bulk of the text is a partial parameter list rather than added meaning.

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 43 parameters, no output schema, and no required-parameter constraints in the schema, the description covers only a small fraction of the surface area. It does explain the return type (progress information), which helps, but an agent still cannot correctly invoke most of the arguments, and the schema's 'required: 0' is in tension with the description's claim that update_set_id is mandatory.

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 43 parameters with 0% description coverage, and the description documents only 5 of them (update_set_id, update_source_id, update_source_instance_id, auto_preview, cleanup_retrieved). Those five carry useful meaning, but 38 parameters — including oddly named ones like force_commit, rollback_installs, remote_update_set_ids — remain completely unexplained, so the description fails to compensate for the coverage gap.

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 ('Retrieves an update set with a given sys_id') and even clarifies the scoping of the sys_id ('on the source instance from where the update set was retrieved'). However, it never distinguishes this tool from close siblings such as update_set_preview, update_set_commit, update_set_back_out, or update_set_create, leaving the agent to infer the retrieve-vs-preview-vs-commit distinction.

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 explicit guidance on when to choose this tool over alternatives, nor any stated prerequisites or ordering (e.g., retrieve before preview before commit). The auto_preview and cleanup_retrieved flags imply a workflow but the description never explains it or warns about irreversible follow-up steps.

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