discover_capability_binding

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

The description transparently discloses the side-effect behavior for saved bindings ('this publishes or refreshes its capabilities in the catalog'), which aligns with readOnlyHint=false and idempotentHint=false. It also clarifies that inline definitions are only previewed ('never saved'), adding behavioral nuance beyond the annotations. No contradiction with annotations was found.

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 sentences, each earning its place: the first states the core outcome, the second contrasts the two usage modes, and the third gives concrete lifecycle context. The most important scoping information is front-loaded, and no filler or redundant wording exists.

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?

The description covers purpose, modes, and workflow but leaves a key gap: it never specifies what constitutes a valid 'full inline definition' (e.g., which of the seven inline fields are required together). With zero required parameters in the schema, an agent could reasonably call the tool with neither binding_id nor an inline definition. The schema's per-field descriptions mitigate but do not close this ambiguity, and there is no output schema to describe the returned catalog entry structure.

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%, providing baseline value. The description goes further by grouping parameters conceptually: binding_id for saved discovery versus the other parameters forming 'a full inline definition' for preview. This mode-level semantics helps an agent understand how to choose among the eight optional parameters without repeating the schema text.

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: 'Discover the capabilities one binding exposes and return them as catalog entries.' It clearly differentiates the two modes (saved binding via binding_id vs inline preview) and references sibling tools (create_capability_binding, list_capabilities), making its role in the capability lifecycle unmistakable.

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 provides explicit sequencing guidance: 'Call this after create_capability_binding, then browse the result with list_capabilities.' It also explains when to use binding_id versus an inline definitioniciously. However, it does not explicitly distinguish this from test_capability_binding or state when not to use it, so the guidance falls short of a full when/when-not specification.

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