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

With no annotations, the description carries the full burden and does disclose real behavior: skill_md's YAML frontmatter is parsed for name/description/prompt/required tools/model, and other params override parsed values, plus the schedule-run consequence. It stops short of permissions, validation limits, or what the call returns, but it is well above a bare imperative.

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?

Three sentences, front-loaded with the core action, then the two modes, then the fallback endpoint. No filler; each clause carries information an agent needs to choose a calling pattern.

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?

For a 6-param create tool with no output schema and no annotations, it covers the creation modes, parameter interlock, downstream lifecycle, and out-of-scope cases. It omits any indication of the return value (e.g., a skill id) and permission/auth requirements, leaving a small gap.

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 100% so the baseline is 3, but the description adds mode-level meaning beyond the individual field docs: it pairs name+prompt as one mode, skill_md as the other, and explains the frontmatter-parsing/override relationship between them. That relational context is useful even though per-field requiredness is already in the schema.

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+resource ('Create a skill') and immediately distinguishes its two creation modes (author with name+prompt vs upload skill_md). An agent can tell exactly what this does and how it differs from siblings like list_skills or delete_skill.

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 names the two invocation paths and their required params, gives the downstream use case (attach to a routine via create_routine's skill_id), and routes the agent elsewhere for zip/GitHub skills (REST POST /api/v1/skills). This is a genuine when/when-not with an alternative.

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