aiworkhub_manager_recipe_register

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

With no annotations, the description carries the full burden and does so well: it discloses pre-write validation with a stable reason_code, duplicate (id, version) refusal that leaves the stored row untouched, and version immutability. These are exactly the failure modes and side effects an agent needs before performing an irreversible write.

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?

Front-loaded 'MANAGER WRITE' marker, then the payload contract, then failure semantics, then a one-line scope disclaimer. Four short units, each carrying distinct information, with no restatement of the name or schema.

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 an unannotated mutation tool with a nested free-form parameter, the description covers the important unknowns: validation order, immutability, duplicate handling, and the no-execution boundary; the output schema covers return values. It omits authorization/prerequisite requirements, the only notable remaining unknown for a write tool.

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 0% and the single `manifest` parameter is a free-form object with additionalProperties, so the description must compensate. It does meaningfully: manifest is declared to be the caller's complete recipe payload, identical in shape to what recipe_show returns, with no field inferred or generated. It stops short of enumerating fields, delegating that to the sibling tool.

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?

Starts with a specific verb+resource ('register and persist one caller-defined tool recipe') and explicitly scopes out execution ('This registers a DESCRIPTION of an invocation. It never runs one.'), which separates it from aiworkhub_manager_recipe_run. It also names aiworkhub_manager_recipe_show as the canonical shape source, so the agent knows how register relates to at least two siblings.

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?

Clear context for when this applies: you have a complete manifest that must be persisted as an immutable version. The 'never runs one' clause implicitly routes execution to recipe_run. It does not, however, disambiguate against the seed tools (recipe_seed_canonical, recipe_seed_plan), which is a remaining gap rather than an error.

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