typora_install_theme

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly indicates a persistent filesystem write to the theme directory and the install-or-update nature of the operation, plus the resulting menu visibility. It stops short of explicitly warning that a same-named existing theme will be overwritten, but 'update' makes that behavior reasonably clear.

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?

A single sentence that front-loads the action ('Install or update'), then gives the destination and outcome with no filler. It avoids repeating parameter names or schema content.

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 two-parameter filesystem-write tool with no output schema, the description conveys enough about side effects and expected results. It would be slightly stronger with an explicit note that installing a theme with an existing name overwrites it, but the operation is simple and the description is functionally adequate.

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?

Both parameters are fully described in the input schema, so the description does not need to re-explain them. The description adds useful context about the target directory and the menu-visible outcome, but it provides no additional meaning about accepted name formats or CSS content constraints beyond what the schema already defines.

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 precise verb ('install or update'), a specific artifact ('custom CSS theme'), a destination ('%APPDATA%\Typora\themes'), and an observable outcome ('appears in Typora's Theme menu'). This clearly differentiates it from sibling tools like typora_set_theme, which applies a theme rather than installing it.

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 implicitly communicates when to use the tool: when you have raw CSS and want a new or updated theme to appear in Typora's Theme menu. However, it does not explicitly contrast this with sibling tools such as typora_set_theme or typora_list_themes, so the usage boundary is left to inference.

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