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

With no annotations provided, the description must carry the burden of behavioral disclosure. "Short catalog" suggests a read-only, informational operation, but it does not reveal the output format, determinism, or whether any of the seven input parameters affect the result. The mismatch between the vague catalog description and the rich input schema further obscures behavior.

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 one short sentence and is easy to scan, with the key noun phrase front-loaded. It is concise, though it sacrifices necessary substance for brevity.

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 is far too incomplete for a tool with seven parameters and no output schema. It never explains which parameters are required, how the catalog is returned, what each entry contains, or how this tool relates to obvious siblings like fetch-status. An agent has almost no basis for invoking this tool 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?

All seven properties in the input schema have their own descriptions (e.g., "Git ref name; discarded after the shape check", "JSON text to validate; discarded after the check"), so schema coverage is high. The tool description itself adds no parameter-level meaning, but with high schema coverage, baseline 3 is appropriate.

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 resource, "common HTTP status codes," and a noun "catalog," so an agent can infer it returns a list of status codes. However, it lacks an explicit verb and mostly restates the tool name, and it does not distinguish itself from sibling tools such as fetch-status beyond the word "catalog."

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?

There is no guidance about when to use this tool versus alternatives, no prerequisites, and no mention of what inputs are expected. The description simply presents a static-sounding catalog, leaving the agent to guess whether this is for looking up a code, interpreting a code, or comparing statuses.

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