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

With no annotations provided, the description must carry the behavioral disclosure. It states the deterministic nature, the kinds of repairs performed, and the return type ('Returns parsed valid JSON object'). It does not cover error behavior or edge cases, but for a repair tool that guarantees a parsed object, this is reasonably transparent.

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 compact and efficient, with the core purpose front-loaded. Every sentence adds value: the repair scope, the specific error types, the return type, and usage restrictions. There is no redundancy or fluff.

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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers the essential information an agent needs: what it does, when to use it, and what it returns. It could mention how it handles unresolvable JSON or whether it throws errors, but for the expected use case it is adequately complete.

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 input schema already has a 100%-coverage description of the single parameter (raw_json) explaining its role as malformed JSON text needing repair. The tool description adds no additional parameter-level details, so the baseline of 3 applies—schema does the heavy lifting.

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 the exact action ('parses and repairs'), the specific resource ('malformed, truncated, or unclosed JSON strings'), and the context (produced by LLMs). It clearly differentiates from siblings by focusing on repair rather than validation or extraction, and names concrete error types (missing brackets, unescaped quotes, trailing commas) that make the purpose unmistakable.

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 explicit when-to-use ('when an LLM produces syntax-broken JSON') and clear exclusions ('do not use on valid non-JSON prose or for modifying data values'). It does not name an alternative sibling directly, but the context is sufficient for an agent to decide when this tool applies versus others.

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