lsp_export_debug_report

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

With no annotations, the description needed to disclose behavioral traits. It does well by stating that the report includes source code and advises reviewing before sharing publicly, which is a critical behavioral warning. It doesn't cover all possibilities (e.g., output format or potential side effects), but the main privacy concern is highlighted, earning a high score.

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 succinct, with a clear first sentence stating the tool's purpose, followed by a bullet-point list of contents, and a 'When to use' section. It is front-loaded with the core purpose and avoids redundancy. Every sentence adds value.

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 the tool's simplicity (one optional parameter) and the presence of an output schema, the description provides sufficient context for an agent to call the tool correctly. It covers what the report contains and when to use it. Could be more detailed on what happens after export (e.g., where the file is saved if no path is given), but that's minor.

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?

The description does not elaborate on the output_path parameter beyond what the schema provides, and the schema coverage is 0%, so the description carries the burden. However, the parameter is optional and simple, and the description implies an output file is needed. With a single optional parameter, the description adds minimal meaning, so a baseline of 3 is appropriate.

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 purpose: to export a debug report for upstream issue reporting. It lists the specific contents (LSP traffic log, open project files, environment info, server stderr) and provides a context for use (after a crash or wrong results). This distinguishes it from sibling tools that perform LSP operations, not reporting.

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 includes a 'When to use' section that explicitly states the scenario: when the LSP server crashed or produced clearly wrong results, and the user wants to help debug upstream. It also mentions the issue tracker URL, which guides the agent on where the report is intended. This is explicit guidance that sets it apart from other LSP tools.

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