agent-lsp

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

With no annotations provided, the description carries full burden and does well. It discloses behavioral traits including: what gets returned (full doc text, signature, source tag), fallback behavior ('falls back gracefully'), failure conditions ('toolchain command fails or language unsupported'), and operational constraints ('without requiring LSP hover response'). It doesn't mention rate limits or authentication needs, but covers most key behavioral aspects.

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?

Three sentences with zero waste. First states core purpose, second adds important constraints and differentiation, third describes return values and fallback behavior. Every sentence earns its place with critical information.

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 4 parameters, 0% schema coverage, no annotations, and no output schema, the description does well but has gaps. It explains what the tool returns and its fallback behavior, but doesn't document parameter meanings or expected formats. Given the complexity, it's mostly complete but could benefit from parameter guidance.

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?

With 0% schema description coverage for 4 parameters, the description must compensate but doesn't explicitly explain any parameters. However, it implies the purpose of 'symbol' and 'language_id' through context ('named symbol', 'language is unsupported'), and mentions 'toolchain sources' which relates to parameters. The description adds meaningful context about what the tool does with the parameters, though doesn't document them directly.

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 specific action ('fetch authoritative documentation'), target resource ('named symbol'), and source ('local toolchain sources'). It distinguishes from siblings by mentioning it works 'without requiring an LSP hover response' and on 'transitive dependencies not indexed by the language server', differentiating it from LSP-based documentation tools like get_signature_help.

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 provides clear context for when to use this tool: when documentation is needed for symbols in transitive dependencies or when LSP hover is unavailable. It doesn't explicitly state when NOT to use it or name specific alternatives, but the context strongly implies it's for non-LSP-indexed symbols.

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