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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: what is repaired, that fixes and parse errors are reported, size limits, offline behavior, pricing, and an alternate HTTPS endpoint. This is rich disclosure beyond structured annotations and does not contradict them.

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 purpose is front-loaded and the dense enumeration is justified by the tool's complexity. The paragraph is long and somewhat run-on, but nearly every clause contributes concrete capability or operational detail.

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?

There is no output schema, so the description carries the burden of explaining returns. It does this by stating that the tool reports every fix, the original parse error, type and size stats, and optional JSONPath results. Combined with the size limit and payment/endpoint context, it is complete enough to call 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?

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning for the optional query parameter by listing supported JSONPath forms such as $.a.b[0], [*], .., slices, unions, and filters, exceeding what the schema alone provides.

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 specific verb and resource: repairing broken or LLM-style JSON into valid JSON. It enumerates the exact repair classes handled, making it easy to distinguish from siblings like format_convert, schema_validate, or validate_batch.

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 gives a clear usage context: use it for broken or LLM-generated JSON and optionally for JSONPath queries on the repaired value. It does not explicitly name alternatives or exclusions, but the intended use case is clear from the repair-focused framing.

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