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

With no annotations, the description carries the full burden, and it discloses the critical non-obvious behavior: the tool does not write the file itself, it returns the content and exact path and YOU must create the file verbatim and report its location. It also notes 'Counts the install.' It does not cover permissions, error behavior, or reversibility, but the surprising side-effect model is well surfaced.

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 core purpose and the caller's responsibility first, then the parameter routing. It is dense with nested parentheticals and could be slightly tightened, but for a tool whose correct invocation depends on post-call steps, every sentence is doing work.

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?

No output schema exists, and the description compensates by stating exactly what is returned (the complete skill file plus the path) and what the agent must do afterward, including where files land per target. Nothing an agent needs to call it and complete the workflow is missing.

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 100%, so the baseline is 3; the description adds real meaning beyond the schema by giving selection logic for target and scope (e.g. project makes the skill committable for the team) and the gating condition for agent=. This is more than a restatement of the enum values.

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 (install) plus resource (a skill) and scope (into the agent you are running in), then goes further to explain the mechanism: the tool returns the skill file and path rather than writing it. This lets an agent distinguish it from siblings like search_skills, get_skill, and submit_skill without opening any 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?

Provides explicit routing conditions: target=hermes for Hermes Agent, target=generic for any other agent, scope=project to keep a Claude Code skill project-local, and agent= only when hosting is enabled with a hosted agent. It stops short of naming the sibling tools to use first (e.g. search_skills/get_skill to find a skill), so it is clear context rather than a full when/when-not map.

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