runrunit_install_cursor_skills

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

With no annotations, the description carries full burden and mostly delivers: it discloses the local-only scope, the copy destination, and recommends dry_run:true first, which signals a filesystem-write operation and a safety workflow. It stops short of describing overwrite/conflict behavior or the return format, but the dry_run guidance is meaningful behavioral context beyond a bare 'installs skills' statement.

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?

Dense and front-loaded: the core action and destination lead, exclusions and alternatives follow, and param hints close. The Portuguese parenthetical ('compartilhar / dividir com o time') is slightly unusual but serves a real disambiguation purpose for Portuguese-speaking users. Every sentence earns its place.

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 tool with 6 optional params, a nested categories object, no output schema, and no annotations, the description covers purpose, scope, when/when-not usage, alternative tools, param semantics, and a safety recommendation. The notable gaps are return-value expectations and file-overwrite behavior, but these are minor given how much context is already packed in.

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. The description adds genuine value beyond the schema by grouping parameters by role (skill_names, categories, target, project_root, source_dir), flagging them as optional, and connecting skill_names to the catalog discovery tool. The 'requires project_root when target is project' detail is already in the schema, so no double credit there, but the grouping and discovery hint justify a 4.

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 names a specific verb-resource pair ('copies bundled Cursor skills from mcp-runrunit into ~/.cursor/skills') and immediately differentiates itself from the sibling share tool. An agent can confidently distinguish this from runrunit_install_cursor_agents and runrunit_share_cursor_skill without inspecting either 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?

Explicitly states when to use ('when the user wants to sync skills onto their machine'), when NOT to use ('NOT for sharing via GitHub'), names the correct alternative (runrunit_share_cursor_skill), and gives a concrete discovery workflow (runrunit_list_cursor_catalog for ids). This is exemplary routing guidance.

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