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

Beyond the read-only and idempotent annotations, it discloses the result shape and each error's JSON path, keyword, and message, which is especially valuable because there is no output schema. It also states that supplying neither or both inputs returns an error result, and nothing contradicts the annotations.

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?

Purpose and result behavior come first, followed by usage guidance and input constraints. Each sentence contributes distinct operational information, and the wording remains efficient without unnecessary repetition.

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 nested two-input validation tool with no output schema, the description covers purpose, alternatives, response contents, input cardinality, mutual exclusivity, and failure behavior. The schema supplies the project structure while get_schema is named for authoring-time validation details, leaving no material invocation gap.

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 description adds the exactly-one-of constraint missing from the top-level schema and explains the choice between inline project and base64-gzipped project_gz based on client payload limits. Together with the nested project schema and detailed project_gz schema description, this supplies the semantics needed for correct invocation despite 50% schema coverage.

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 opening sentence identifies the operation, "Server-side schema validation," and the resource, "a project config," narrowing the broader title to schema validation rather than general correctness checking. The comparison with local validation via get_schema also distinguishes it from that sibling.

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?

It explicitly prefers local get_schema validation during authoring and positions this tool as the ground-truth check, including before returning an amended model to the user. It also specifies when project_gz is appropriate, providing concrete selection guidance for both the tool and its input modes.

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