aiworkhub_manager_skill_usage

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

Annotations already declare readOnlyHint=true, and the description reinforces the boundary with 'Read-only. It never activates, retires or evidences anything.' It also adds real context beyond annotations: the figures are derived from persisted selection receipts and from canonicalized actor identities ('two spellings of one manager count once'), and the exact named gate reasons are disclosed. It stops short of describing cost, ordering, or behavior when no skills exist.

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 purpose is front-loaded in one line, followed by a single dense enumeration and a closing scope disclaimer; each element earns its place, and the reason-code list is formatted for scanning. The mid-sentence indentation of the four codes is slightly awkward but not wasteful.

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?

With an output schema present, the description need not explain return values, and it still covers what is measured, the basis of measurement, and injectability semantics. The only substantive hole is the undocumented min_accepted_evidence parameter, which leaves a caller unable to reason about filtering.

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?

The one parameter, min_accepted_evidence, has 0% schema description coverage and is never mentioned in the description, so an agent must guess that it is a threshold filter over accepted evidence rows and how it interacts with the reported metrics. The phrase 'activation_evidence_below_two_distinct_actors' faintly mirrors the default of 2 but does not document the parameter itself.

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 opening line gives a specific verb and resource ('per-skill usage statistics, measured from the stored record') and the enumeration that follows pins down exactly which metrics are returned (version counts, evidence rows by outcome, canonical actor counts, injection receipts, injectability). That detail effectively separates it from neighbours like skill_retirement_report or recipe_usage, but no sibling is ever named, so differentiation is inferred rather than stated.

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?

Usage is only implied: an agent can infer this is the diagnostic to consult before proposing, activating or retiring a skill, since the description lists the exact blocking reasons. There is no explicit when-to-use / when-not statement and no pointer to an alternative tool for the adjacent questions (retirement reporting, recipe usage).

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