Verify Generation

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real domain context — the tool never mints or reuses a concept id and surfaces a named dependency_blocked/ConceptAuthorityUnavailable error — but it frames this around 'mutating action,' language that does not apply to a read-only verify tool, and says nothing about what a successful verification reports or whether it can fail on claim mismatch.

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 first line names the tool and its family, which is good front-loading, but the remaining prose is dominated by family-wide authority-port philosophy rather than this tool's specific job. Given 26 parameters and a single verify operation, a large share of the text does not earn its place for the caller.

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?

This is a high-complexity tool (26 params, nested candidate/generation payloads) and the description never addresses the core operation, required inputs, or success/failure semantics of a verification. An output schema does exist, so return-value detail is excused, but the invocation-side explanation is far short of what an agent needs.

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 100%, so all 26 parameters are already documented by the schema (including the 'For verify_generation' tags on generation, candidates and repo_path). The description adds no parameter-level meaning such as payload shape or which fields matter, so the baseline 3 applies.

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 the tool name and says it is 'concept-id claim coordination against RMDD-16's central authority,' but never explains what verifying a generation actually does (e.g., validate a Generation contract, diff a repo, check that candidate ids match a claim). Siblings rm_concepts_verify_candidate and rm_concepts_reconcile are never contrasted, so an agent cannot tell this tool apart from them from the text alone.

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?

There is no explicit when-to-use guidance and no routing to alternatives such as rm_concepts_verify_candidate or rm_concepts_get. The only conditional stated ('when the central authority is unavailable ... every mutating action refuses') describes failure behavior for mutating family actions, not when an agent should reach for verify_generation.

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