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

Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds the fact that escaping covers the five special HTML characters and that unescape handles named/numeric entities, which is behaviorally useful. However, it doesn't disclose edge cases like double-encoding behavior, unknown entity handling, or whether output is a string. With annotations covering the safety aspects, a 3 is appropriate: this is the baseline 'adds some value' score, not higher because the description doesn't explain what happens with invalid entities or mixed input.

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?

One sentence, no wasted words, and the key operation (escape) is mentioned first. The inclusion of the source URL is borderline, but it's a single short addition and doesn't hurt. The front-loading of the five characters and the purpose ('safe to place in HTML') is effective. It loses one point because the sentence is dense and could be seen as slightly over-explaining, though it remains efficient.

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 tool is simple (2 params, no nested objects, has output schema), and the description covers the operation, the characters involved, and the mode distinction. The output schema exists, so the description doesn't need to explain return values. The only real gap is that it doesn't mention input size limits or invalid input behavior, but for a simple utility like this, those are minor. The source link also hints at documentation for edge cases.

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%, so the schema already fully documents both parameters, giving a baseline of 3. The description adds meaning by explicitly telling the agent that 'escape' converts to entities and 'unescape' converts entities back to plain characters, which aligns with the enum semantics. It also clarifies the mode-text relationship ('text to escape' vs 'HTML with entities to unescape'). This is slightly above baseline but not a full 5 because the schema already covers the parameter meanings well.

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 clear dual action (escape/unescape), names the exact five special characters, and specifies the safety context. The mode parameter already disambiguates the two operations, but the description's explicit enumeration of the five characters and the purpose ('so text is safe to place in HTML') makes the tool's scope immediately obvious. It is easily distinguished from siblings like hopi_url_encoder or hopi_special_characters.

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 states what it does (escape or unescape) and the source URL is included, but there is no explicit 'when to use this vs alternatives' guidance. There are no sibling tools that do HTML escaping in the list, so the absence of explicit alternatives is less damaging, but the description doesn't mention when unescaping would be preferred or any safety caveats. Usage is implied rather than explicit.

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