agy_install_skill

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

With no annotations, the description fully bears the transparency burden. It details exact filesystem paths per scope, the force flag behavior (skip vs. unconditional rewrite), and the reasoning behind using ~/.agy/ over ~/.gemini/ due to a standing rule. This is rich behavioral context.

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 description is a single well-structured paragraph, front-loaded with the main action, then logically covering targets, scope paths, the Antigravity exception, and force semantics. Every sentence adds necessary context without waste.

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?

Given 4 parameters, 0% schema coverage, and existing output schema, the description covers all parameters, defaults, and edge cases, leaving no significant ambiguity for an agent to decide when and how to invoke the tool.

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 0%, and the description compensates thoroughly: targets values are enumerated, scope modes are tied to concrete paths, project_root is explained, and force behavior is defined for both false and true.

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 opens with a specific verb+resource: 'Install the agy-mcp collaboration skill bundle into one or more agent platforms.' It clearly differentiates from sibling tools like agy_start or agy_status by focusing on installation.

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?

The description explains target expansion and scope semantics, giving clear context on parameter choices. It does not explicitly name alternatives or exclusions, but the tool's purpose is self-contained and sibling names clearly differ.

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