emu_get_contracts_catalog

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

With no annotations at all, the description carries the full burden of behavioral disclosure, and it provides none beyond the data contents list. It doesn't disclose anything about performance, large payloads, caching, authentication, or any operational trait. It does clarify that the return is a catalog of metadata rather than raw contract definitions, which is some but minimal 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?

A single sentence that front-loads the resource ('v2 contract catalog') and the action ('Returns') before enumerating the metadata domains. Every phrase earns its place, and there is zero 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 zero-parameter read-only tool with no output schema, the description covers the main purpose and data scope but not the broader retrieval context. Missing is any explanation of how this catalog relates to the many sibling contract tools (e.g., versions, AXL, OpenAPI) or what an agent should do with the returned catalog vs those alternatives. It's adequate for parameter-free invocation but not complete for a tool sitting in a large family of similarly-named contract endpoints.

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 tool takes zero parameters, so there is nothing for schema or description to compensate for. The description usefully enumerates the types of content in the returned catalog (typed AXL operation metadata, coverage summaries, resources, capabilities, state collections), which adds concrete semantic value about what the agent will receive. This is a no-parameter tool, so the baseline of 4 applies.

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 the resource (v2 contract catalog) and the action (returns). It lists the contained metadata domains (typed AXL operation metadata, coverage summaries, resources, capabilities, state collections), which tells the agent what to expect. It doesn't explicitly distinguish from sibling tools like emu_get_contracts_versions or emu_get_contracts_axl, though the 'catalog' and 'v2' hints are differentiating enough.

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 is entirely declarative with no guidance on when to use this tool versus alternatives such as emu_get_contracts_versions, emu_get_contracts_axl, or emu_get_contracts_openapi_json. There's no mention of context, prerequisites, or when this catalog would be appropriate over sibling contract tools. The agent must infer its usage role among many similar contract and catalog tools.

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