Describe One Operation

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the description only needs to add context, and it does: it discloses that failures are surfaced as CONFIG_ERROR and that the error names the nearest key. It does not mention limits on size or response shape beyond the output schema, but the safety profile is consistent with the annotations (no contradiction).

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 dense sentence with the key constraint and the error behavior front-loaded, and nothing restating the name or title. The enumeration ('input contract, effect, dry-run support, errors and usage') is compact but slightly telegraphic, and the parenthetical repeats the schema's 'never a tool name' warning.

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 one-parameter read-only introspection tool with an output schema, the definition covers purpose, valid input form, failure mode and what the caller learns, so nothing needed to invoke it correctly is missing. Return-value details are correctly left to the output schema.

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 coverage is 100% with a single required parameter already documented as a canonical operation key copied exactly from hudu_list_operations, so the baseline is 3. The description adds real value on top by specifying the consequence of a malformed value (CONFIG_ERROR naming the nearest) and by ruling out tool names and fuzzy matching, reducing invalid calls.

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?

States a specific verb and resource ('describe ... ONE operation') plus the invocation form ('by exact catalog key, never a tool name'), which cleanly separates it from hudu_list_operations (enumerates keys) and hudu_read (executes an operation). An agent can tell what it gets back: input contract, effect, dry-run support, errors, usage.

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?

Makes the precondition of an exact catalog key explicit and warns that tool names are not accepted and there is no fuzzy match, which is the main misuse risk. It stops short of stating the intended flow (call hudu_list_operations first, then hudu_describe_operation, then hudu_read) or any when-not condition.

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