validate_json

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which the description complements rather than contradicts. It adds behavioral context beyond annotations: 'No signup' indicates no auth, and 'No schema validation or code execution' clarifies it is purely syntactic. These extras enhance the agent's understanding of side effects and limitations.

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?

Two succinct sentences front-load the primary purpose, then add non-obvious constraints. There is no verbosity or redundancy; every clause earns its place. The structure is clean and easily scannable.

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 simple tool with two parameters and no output schema, the description covers the core functionality, exclusions, and auth requirements. It omits details about the return value (e.g., whether invalid JSON returns an error), but given the simplicity and annotations, this is a minor gap. The description is complete enough for an agent to invoke it correctly in most expected scenarios.

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 0%, so the description carries the burden of explaining parameters. The phrase 'optionally format it' directly clarifies the 'format' boolean, and 'Validate JSON syntax' implies 'text' is the JSON string. While it doesn't discuss maxLength or formatting details, the description adequately maps to both parameters and adds meaning beyond the bare schema.

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 ('validate') and resource ('JSON syntax'), and adds an optional formatting capability. It also explicitly excludes schema validation and code execution, making its scope unambiguous. No sibling tool overlaps with this JSON-specific function.

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 provides clear context for when to use the tool—whenever JSON syntax validation or formatting is needed—and states exclusions ('No schema validation or code execution'). It does not name alternative tools, but given the unrelated siblings, the guidance is sufficient. The 'No signup' note also clarifies that no authentication is required.

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