Matrix42 web service discovery

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

Beyond the readOnlyHint annotation, the description details per-action behavior, including return shapes for list_operations, the nature of api_overview content, and the required inputs for describe_operation. It also clarifies that the tool is metadata-only and references authentication conventions as discoverable content, providing meaningful behavioral context.

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 dense but well-structured, front-loading the core purpose and then systematically covering each action, its parameters, and the typical flow. Every sentence carries actionable 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?

For a multi-action discovery tool with no output schema, the description is exceptionally complete: it defines all actions, their return content, parameter usage, and a recommended call sequence. An agent has enough information to select the right action and parameters for a discovery task.

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 already documents all five parameters with a high coverage level, so the baseline is 3. The description adds value by mapping each parameter to the action it affects, explaining search and service_id filtering semantics, and noting operation_id's requirement for describe_operation.

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 identifies a specific verb ('Discover'), a specific resource ('Matrix42 REST API of the connected instance'), and its read-only metadata nature. It enumerates four distinct actions with concrete outputs, so an agent can understand the tool's scope and distinguish it from data-query or schema-related 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 clear context for when this tool is useful: reasoning about the API or writing standalone integration code. It also provides a typical discovery flow, but it does not explicitly name sibling tools or state when not to use it, so it stops short of a full when/when-not comparison.

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