validate_draft

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

With no annotations, the description carries full responsibility, and it is exceptionally transparent: it enumerates checks (template, enum, regex, DOI registry, Wikidata), defines the three severities, explains placeholder conventions, notes step inference from filenames, and describes the unfilled-skeleton behavior. This goes well beyond a generic 'validates' statement.

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 long but every sentence earns its place, and it is well-structured: purpose first, then usage, then severity semantics, then edge cases. The severity block and placeholder convention explanation are dense but 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?

Given no output schema or annotations, the description covers purpose, usage, validation behavior, severity semantics, placeholder conventions, and step handling. The main gap is the unexplained `live` parameter, and the return value shape is only implied via `publishable` and severities.

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 must explain all parameters. It richly explains `step` (inferred from filename, override for unusual names) but says nothing about `path` or, more importantly, `live`, whose boolean semantics and default true are not inferable from the 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?

States a specific verb and resource: 'Check one drafted nanopub against its template and the real world.' The singular 'one drafted nanopub' and the focus on template/real-world validation distinguish it from siblings like validate_drafts and validate_chain_draft without needing to open schemas.

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?

Explicitly instructs 'Run this on every draft before publishing' and positions it as the pre-flight checklist, which is strong when-to-use guidance. It does not name alternative tools or state when not to use them, so it stops short of full exclusionary guidance.

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