Validate a problem

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

The description goes beyond the readOnlyHint annotation by specifying what kinds of problems are reported: missing/empty fields, non-URL-safe slugs, bad difficulty, non-positive limits, and malformed test cases. It also reveals that every issue is reported, not just a pass/fail result.

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 sentences, front-loaded with the operation and validation criteria, followed by a concise usage instruction. Every clause adds relevant information with no wasted words.

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 single-parameter tool with a fully documented schema and an output schema present, the description fully covers behavior and usage context. An agent knows what input to provide, what the tool checks, and when to call it.

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 schema already documents problem_json as a JSON object string. The description adds minimal semantic value, referring to 'a problem object' and implicitly defining what the validator checks, but does not materially expand on the parameter itself.

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 uses a specific verb ('Check') and resource ('a problem object against Repovive's schema') and enumerates the exact categories of issues found. This clearly distinguishes it from related build/judge/push tools and leaves no ambiguity about what it does.

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 explicit instruction 'Run it before pushing a draft' gives a clear, actionable trigger for when to invoke the tool. While no alternative tool is named, none exists among siblings for this exact validation purpose, so the usage guidance is sufficient.

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