List service applications

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds the auth requirement ('applications:read') and an interpretive caveat ('a queued state is not proof of health') that an agent would not get from structured data. It adds value beyond the annotations without contradicting 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?

Three tight sentences, front-loaded with the core action, then auth requirement and a caveat. 'A queued state is not proof of health' is somewhat cryptic and would benefit from a hint at what it implies for the caller, but nothing is wasted.

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

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

For a single-parameter read tool with no output schema and annotations already declaring the safety profile, the description covers scope, permission requirement, and a state-interpretation caveat. Adequate, though the pending-checkout/queued-state semantics remain slightly under-explained.

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 on the single orderNo parameter, the schema already carries the format and pattern details. The description's 'one owned service' reinforces that orderNo identifies the service but adds no syntax 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?

Specific verb ('List') plus a precise resource ('managed application installations and any pending checkout selection') scoped to 'one owned service'. It distinguishes itself well from list_services and list_application_catalog, though it doesn't name a sibling 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?

The 'for one owned service' constraint and 'Requires applications:read' prerequisite imply the context in which this applies, but it never states when to use this versus get_application_installation, list_services, or list_application_recipes. Usage is implied rather than prescribed.

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