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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond those hints: it reveals the dual-hash normalization, that field renaming requires an explicit bijection, and that supplied rules make scalars and whitespace significant. This is valuable behavioral information about how the comparison operates rather than just a side-effect note.

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 only a few lines and ends quickly, but it includes a clear typographical stumble ('content_hash is content_hash normalizes') and a filler phrase 'content_hash is' that could be removed. It is compact, yet the redundancy and slightly awkward wording keep it from being fully polished.

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?

Despite the 8 parameters and absent output schema, the description never explains what the tool returns (a boolean, a hash, a diff, an object?), and it does not mention constraints_a/b at all. It also assumes the reader understands 'dual-hash design' without describing the return format. Since there is no output schema and some parameters, the description should bridge more of that gap, and fewer than 2 the task gets a 2.

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?

With 100% schema description coverage, the baseline is 3, but the description goes further by explaining the role of field_mapping ('renaming requires an explicit bijection') and rules_a/rules_b ('With supplied rules, scalar types and whitespace remain significant'). It does not say anything about constraints_a/b or payload_a/b beyond what the schema provides, but the added interpretation of key tricky parameters elevates it above the baseline.

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 opens with a concrete verb and object ('Compare two payloads'), and frames the tool under a 'dual-hash design', making the main goal apparent. It also helps differentiate itself from structural comparison by ending with 'Structural similarity alone does not establish decision equivalence,' which positions it as a semantic instead of a syntactic check. The phrase 'dual-hash design' is jargon and the opening line stumbles with a repeat, keeping it from a 5.

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 direct statement of when to use this tool versus siblings such as structural_types or validate. However, the description implies usage through the emphasis on semantic marginals, field roles, and the line 'Structural similarity alone does not establish decision equivalence', which hints that semantic comparison is needed when decision equivalence matters. Because the guidance is implicit rather than explicit, it receives a 3.

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