skill_manifest

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the qualifier "shared", implying a scoped subset of skills rather than everything the harness knows, which is genuinely useful context. It does not explain why idempotentHint is false for a list operation or what "metadata" contains, so it adds only modest value beyond the annotations.

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?

One short sentence with no filler and the resource stated up front. It is arguably a touch thin rather than bloated, so the brevity is efficient even if it leaves gaps elsewhere.

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?

There is no output schema, so the description carries the burden of telling the agent what comes back. Saying only "their metadata" leaves the shape of the response unspecified, though for a trivial 0-parameter list tool this is a minor rather than fatal omission.

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?

With zero parameters there is nothing to disambiguate, so the baseline of 4 applies. The description correctly signals a no-argument call rather than leaving the agent hunting for filter options.

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 uses a specific verb ("List") and a specific resource ("shared skills exposed by the harness"), plus the payload ("their metadata"). That is enough to separate it from siblings like harness_inspect or self_augment, though it never names those siblings explicitly.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as harness_inspect, which an agent could easily confuse this with. The only implicit cue is that this is a discovery call, which the agent must infer.

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