Search installed applications

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds behavioral details: matching logic (exact/prefix/substring), optional os filter, return shape (installed versions possibly null, image keys, OS, architecture), and the distinction between truncated results and empty results versus catalog errors. It also clarifies it never allocates, which adds safety context beyond 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 comprehensive yet efficient, leading with the core purpose, then matching behavior, then return semantics, and ending with what it does not do. Every sentence adds distinct value with no 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 no output schema, the description explains return values (installed versions, image keys, OS, architecture) and handles edge cases (null versions, truncated results, empty vs error). It also specifies the optional filter. For a search tool, this covers everything an agent needs to call 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?

With 0% schema description coverage, the description fully compensates by explaining the 'name' parameter as matching by exact, prefix, and substring, and the 'os' parameter as an optional hard filter with enum values linux/macos. This gives meaning beyond the schema's bare property definitions.

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 clear verb 'Find' and resource 'installed application in the image inventories', and it explicitly differentiates from relay_acquire by stating it is optional before acquiring and does not choose an image. This distinguishes it from sibling tools like relay_acquire and relay_probe.

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 states it is optional before relay_acquire, and clarifies what it never does (allocates, boots, installs, reserves capacity, chooses an image), guiding when to use it. It does not explicitly name alternatives, but the context of being a search step is clear. The 'optional before relay_acquire' provides a clear usage slot.

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