aiworkhub_manager_skill_propose

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 thoroughly: mechanical fields are copied server-side, disagreeing mechanical inputs are refused (never silently overridden), out-of-vocabulary values are rejected before any write, duplicate identity/version is refused without overwriting, and the record is never ACTIVE on creation (activation needs evidence from two distinct actors). This is exactly the kind of write semantics an agent cannot infer from schema alone.

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?

Long, but front-loaded with the core action and the candidate_id workflow before the vocabulary block, and the closed-vocabulary listing is genuinely useful content rather than filler. Slight cost: the enum dump is dense prose that could be compressed, but nothing is redundant.

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?

An output schema exists, so return values needn't be explained, and the description covers everything else an agent needs: input sourcing, server-side vs caller-supplied field split, validation/refusal behavior, and post-write state (never ACTIVE). Nothing material is missing for correct invocation.

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%, so the description must compensate, and it documents most of the 14 params with closed vocabularies, regexes for identity, semver form for version, relative-path constraint for path_or_symbol, and the [0,1] float range for confidence. The notable gap is preferred_tools, which is never mentioned, and procedure_steps/avoid_rules are named but not described beyond being judgement fields.

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 ("register and persist one proposed skill") and immediately scopes it as a MANAGER WRITE, which separates it from read-side siblings like skill_mine and from skill_activate. An agent can tell which skill-lifecycle stage this tool owns without opening the schema.

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 routes the caller to aiworkhub_manager_skill_mine to obtain candidate_id and states the branch condition (with candidate_id only judgement fields are needed; without it every field is required). It also clarifies that activation is a separate decision, so the agent knows this tool is not the activation step. It does not state when proposing is inappropriate, but the workflow context is clear.

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