aiworkhub_manager_skill_mine

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

Annotations declare readOnlyHint=true and the description reinforces it ('Read-only'), then adds behavior the annotations cannot convey: vocabulary normalization before comparison, recurrence gating across distinct cards/files, what each candidate carries (card ids, request ids, partially blank draft), and the downstream two-actor activation gate. This is real context beyond the structured fields.

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 with the verb and the read-only framing before any mechanics, and each subsequent sentence adds distinct information (clustering rule, promotion gate, output contents, downstream handoff). It is longer than typical but dense with usable detail rather than padding.

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 shape needn't be spelled out, and the description still sketches what a candidate contains and why the draft is incomplete (closed-vocabulary dimensions left blank for the manager). Read-only safety and downstream gating are covered; the only real gap is the unexplained threshold and include_sensitivity knobs.

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 carry parameter meaning, and it explains only two of four: min_cards ('recurred across at least min_cards distinct cards') and min_files ('in min_files distinct files'). 'threshold' and 'include_sensitivity' are never mentioned, and threshold's default 0.22 gives no hint of what it measures (presumably a similarity or clustering cutoff).

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 ('mine the correction record into gated skill PROPOSALS') and explains the mechanism: clustering by asserted rule with instance vocabulary stripped, then promotion by recurrence thresholds. It also explicitly distinguishes itself from aiworkhub_manager_skill_propose and aiworkhub_manager_skill_activate, so an agent knows this is the read/analysis step, not the write step.

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 routing: it says the returned draft reaches the store only if handed to aiworkhub_manager_skill_propose, and that activation is separately gated — which tells the agent this tool cannot complete the workflow alone. It does not state explicit preconditions (e.g. how much correction history must exist before mining is worthwhile) or when-not-to-run, so it falls short of a full 5.

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