swebsy_promote_to_symbol

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

With no annotations, the description carries the behavioral burden. It discloses side effects: 'REPAIRS broken linkage... re-promoting an orphaned copy rebuilds its main and re-links every other copy of it, and re-promoting a symbol registers instances it had lost.' It also reveals output behavior (returns symbol id and repaired count) and the 'detached' condition. It does not mention permission requirements or whether the operation is reversible, but overall it is quite transparent.

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 paragraph but packs necessary detail. It front-loads the main purpose and then explains repair behavior and alternatives. While dense, every sentence adds useful information without fluff. It could be slightly more structured, but it is appropriately sized for the tool's complexity.

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 mutation tool with no output schema, the description covers return values (symbol id, repaired count, detached), and gives alternatives for detached cases. It references related tools (read_page, list_symbols, add_symbol_instance, delete_section). Missing details include what happens if a symbol with the same name exists or edge cases, but overall it provides enough context for correct invocation.

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% (both parameters have descriptions), so baseline is 3. The description adds value by explaining the origin of targetPath ('exactly as returned by read_page') and the meaning of the return value. This goes beyond the schema's field descriptions, improving semantic understanding.

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 clearly states the tool's primary purpose: 'Promote an existing component into a reusable SYMBOL so it can be shared, in sync, across pages.' It also specifies the resource (component) and the action (promote), and distinguishes its secondary repair role. It differentiates from siblings by referencing read_page for input and mentioning alternative tools for detached copies.

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 gives explicit when-to-use context: 'Pass its `targetPath` from read_page' with examples, and explains the repair scenario. It also provides an explicit when-not-to-use: 'copies whose structure has diverged too far are reported as `detached` — delete_section + add_symbol_instance those instead.' This clearly routes the agent to alternatives.

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