lsp_signature

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

With no annotations, the description carries the behavioral disclosure burden, and it does so well by explicitly warning that signatureHelp is on the scheme-langserver roadmap and may return -32601 'method not found'. This is a valuable behavioral trait that an agent needs to handle gracefully. It does not discuss side effects, but as a read-only LSP query that is a minor omission.

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 concise and front-loaded with the core purpose, followed by a single, clearly marked limitation. Every sentence earns its place, and the fallback instruction is easy to notice.

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?

The description covers purpose and a key limitation, and an output schema exists to explain return values. However, the parameter semantics gap and lack of positional details make the tool not fully self-contained for correct invocation, especially given no annotations are available.

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 description coverage is 0%, so the description must compensate by explaining file_path, line, and character semantics. It only mentions 'at the given position', which does not explain coordinate bases, whether positions are zero-based, or how the file_path locates the document. The parameter names are self-evident but not sufficiently documented.

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 uses a specific verb and resource: 'Get signature help for a function call.' It goes further by stating what the tool shows ('parameter names and types'), making its purpose unambiguous. This clearly distinguishes it from sibling tools like lsp_hover or lsp_complete.

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 intended use is implied from the purpose: call this when a function call is being made and signature details are needed. However, there is no explicit guidance on when to prefer this over alternatives such as lsp_hover or lsp_complete, and no when-not-to-use conditions besides the error fallback note.

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