list_tools

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description need not restate it. The description adds the content scope of the catalog (the categories of tools returned), which is modest but real value. It omits what the response actually looks like (names only vs. names plus descriptions vs. pagination), which matters for a discovery call whose whole point is the return payload.

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?

It is compact and dense with real content, so no sentence is padding in the literal sense. However it is not front-loaded with a purpose statement — the sentence opens mid-catalog and trails off with an ellipsis ('... rename...'), signalling an incomplete enumeration rather than a defined contract. A one-line 'Returns the utility tools available, optionally filtered by query' would do more work than the list.

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-config discovery tool with no output schema, the description should explain what comes back and how to use 'query' to narrow it; it does neither. Given that the agent's next move (describe_tool → run_tool) depends entirely on reading this result, the omission is more consequential than it would be for a leaf operation.

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 single optional parameter 'query' has 0% schema description coverage, and the description says nothing about it — not whether it is a substring match, a keyword filter, or semantic search, and not what omitting it returns. With one param and no schema documentation, the description was the only place this could be explained and it is silent.

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 never states a verb or what the tool returns; it enumerates a catalog of utility tools (palette, histogram, OCR, PDF, etc.), which only implies 'lists tools' when combined with the tool name. The enumerated domains are genuinely informative about scope, but the purpose itself must be inferred rather than read. It also gives no signal distinguishing it from describe_tool or run_tool, which are the natural next steps in a discovery flow.

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 when-to-use guidance at all: nothing says to call this before describe_tool/run_tool, nothing about how it relates to get_capabilities or list_operations, and no conditions under which to prefer it. The agent is left to infer the entire discovery workflow from sibling names alone.

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