Add or remove a project reference

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

Beyond the destructiveHint annotation, the description discloses concrete behavioral details: it always saves the file, resolves library names primarily on Windows, rejects ambiguous matches, and refuses specific destructive mutations like removing Microsoft Forms while a UserForm exists. This gives the agent accurate expectations for edge cases.

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 dense but every sentence carries necessary information: core action, use cases, naming resolution, refusal conditions, and platform requirements. It is front-loaded with the primary verb and resource, and the added complexity is justified for a tool with this many edge cases.

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 7-parameter tool with an output schema and fully documented parameters, the description still adds what the schema cannot: workflow triggers, naming resolution behavior, platform differences, and failure refusal conditions. It is complete enough for an agent to invoke it correctly in both common and exceptional cases.

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 valuable cross-parameter meaning by explaining how the library parameter is interpreted ('Excel, Word, PowerPoint and Access work anywhere' or 'by the name code writes'), and when guid/version become necessary ('Off Windows, pass guid and version').

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 states a specific action ('Adds or removes a type library reference in a VBA project') and clearly indicates the file is saved. It distinguishes this from sibling tools like xlide_list_references by focusing on mutation rather than inspection.

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 triggers: 'when xlide_analyze reports missing-library-reference' and 'when code needs early binding, as Dim d As Scripting.Dictionary does.' It also covers important conditions like platform-specific requirements and refusals, though it does not explicitly name an alternative tool for inspection-only tasks.

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