install_stanza

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It adds only "if needed" (hinting at conditional/idempotent behavior) and the core/on_demand target distinction, but does not disclose side effects — whether this mutates project state, replaces an existing stanza, requires the pack to be fetched first, or what happens on conflict. For an install/mutation tool this is a significant gap.

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 brief at three short sentences, but the "shelf" metaphor costs more clarity than it saves, and the ordering buries the actionable instruction behind a domain statement. It is compact, yet the compactness is achieved at the expense of precision rather than through efficient wording.

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 parameters (4 required), zero annotation coverage, and no parameter documentation, the description is far too thin. It never explains the installation workflow, prerequisites (e.g., whether fetch_pack must run first), behavior of the nullable pack field, or what distinguishes this from install_capability/install_skill. The output schema exists but cannot compensate for missing operational context.

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%, so the description must compensate. It partially explains target ("core or on_demand") and hints at the stanza/version/pack relationship, but leaves working_folder and project entirely unexplained, and does not clarify the nullable pack parameter. Most of the 6 parameters rely on inference from parameter names alone.

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 is cryptic: "This project uses one stanza from a pack version. Pull onto the shelf if needed." It never explicitly states that the tool installs/associates a stanza with a project, and the metaphor "shelf" is undefined. It is less than a pure tautology since it hints at a domain constraint, but an agent cannot determine the actual action being performed with confidence.

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?

No guidance is given on when to use this tool versus its many siblings (install_capability, install_skill, uninstall_stanza, fetch_pack). The phrase "This project uses one stanza from a pack version" implies a constraint, and "target is core or on_demand" clarifies a parameter, but neither explains selection criteria or conditions that would route an agent here instead of an alternative.

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