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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It states the tool "never throws and never partially accepts a spec," defines the error/warning distinction, and discloses that missing keys are reported alongside the fields a block does have. This gives the agent a clear mental model of the tool's behavior before calling it.

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?

Every sentence earns its place: action, result semantics, usage timing, exclusivity, and error-based field discovery are each covered in dense but readable sentences. The core purpose is front-loaded, and the parenthetical examples are concrete without bloating the description.

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 simple one-parameter schema, no annotations, and no output schema, the description supplies all essential operational detail: what the tool checks, what it returns, how to interpret errors and warnings, when to use it, and how to extract schema knowledge from error messages. The absence of an explicit output schema is mitigated by the promise of "structured errors and warnings" and the field-naming behavior.

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 schema only defines a single `calendar` object with `additionalProperties: true`, so the description must compensate for the 0% schema coverage. It does this by identifying the input as the spec to validate and explaining how errors reveal the valid fields. It stops short of enumerating the block types or field names, but it explicitly tells the agent the tool itself will provide that information when needed.

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 specific action and resource: "Check a calendar spec and list everything wrong with it." It clearly separates this tool from the sibling date/calendar operations by noting it is "the only tool that accepts a malformed spec," so an agent can identify its unique role as a validator.

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 direct rule: "Use this before any other tool when you have written or edited a spec yourself." It also explains that this is the only tool that accepts malformed specs, which tells the agent when no other tool can substitute. The distinction between errors and warnings further clarifies how to interpret results when deciding next steps.

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