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

With no annotations, the description is the only behavioral disclosure: it correctly identifies the tool as a read-only trace and explains the default-incoming branch. It leaves out notable behavior such as whether it works without a prior prepare_call_hierarchy call, whether results are scoped to the project/index, and any latency or size concerns for deep call graphs.

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?

Two short sentences, front-loaded with the core action and the direction switch, with no filler. It is efficient to the point of under-specification, but nothing written is wasted.

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?

An output schema exists so return values needn't be described, but for a 5-parameter LSP tool with zero schema coverage and no annotations the description is too thin: missing position semantics, the role of symbol_name, and the relationship to the prepare_call_hierarchy sibling are all conditions an agent needs to call this correctly.

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 carry parameter meaning, yet it explains only 'direction' (partially – incoming/outgoing) and never defines file_path, line, character, or symbol_name. A caller cannot tell whether the position is 0- or 1-based, what units 'character' uses, or why symbol_name is optional.

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?

States a specific verb and resource ("Trace caller/callee relationships for a function or method") and disambiguates the two directions, so an agent knows it is a relationship-tracing tool. It does not distinguish itself from the similar sibling prepare_call_hierarchy or find_references, so the agent must guess at the boundary.

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 direction values give implicit guidance on which mode to pick, but there is no explicit when-to-use versus find_references/get_type_hierarchy/prepare_call_hierarchy, and no statement of prerequisites (e.g. whether a prepared hierarchy is required first). Usage is inferable but not stated.

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

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

With no annotations, the description has to carry the full burden. It usefully discloses one non-obvious output behavior (struct fields and enum members collapsed into 'fields_count' unless include_fields=True), but says nothing about error conditions, LSP dependency, or what query and max_depth do.

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 tight sentences, front-loaded with the core action, followed by the usage rationale and then the one caveat that changes output shape. Nothing is redundant, though the caveat could sit closer to the parameter it governs.

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?

An output schema exists, so return values need not be spelled out, and the fields-collapsing note covers the main return-value surprise. However, for a 4-parameter tool with zero schema coverage, the undefined query and max_depth leave real gaps an agent must guess at.

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% across 4 parameters, and the description only explains include_fields. The purpose of 'query' and the effect of 'max_depth' are undocumented in both the schema and the description, leaving half the parameters opaque.

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?

States a specific verb and resource ('Retrieve outline of classes, methods, functions, and properties in a file') and the scoping to a single file implicitly distinguishes it from the sibling workspace_symbols. It stops short of naming that sibling, so the differentiation is left to inference.

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?

'Use to quickly understand file architecture without reading all lines' gives a use context, but it frames the benefit rather than conditions. There is no guidance on when to reach for workspace_symbols instead, or on prerequisites such as an active LSP server.

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

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

With no annotations, the description carries the full burden. It discloses the return shape in broad terms (file locations and compact line numbers) and implies a read operation, but it does not discuss permissions, rate limits, or behavior of optional flags.

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 short sentences, front-loaded with the core action and return behavior. There is no wasted text.

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?

An output schema exists, so return values need not be fully explained. But for a seven-parameter tool with no annotations and 0% schema description coverage, the description leaves critical parameter semantics and invocation guidance incomplete.

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 schema has seven parameters and zero description coverage, so the description must compensate. It mentions symbols and locations only generically and does not explain file_path, line, character, limit, symbol_name, include_snippet, or include_declaration.

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 verb and resource: finding references and usages of a symbol across the workspace. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as go_to_definition or rename_symbol.

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?

It gives a clear use case: assessing the impact of changes. However, it does not state when not to use it or name alternatives like go_to_definition or rename_symbol.

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

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

No annotations are provided, so the description carries the full burden; it does disclose the returned content (errors, warnings, code hints) and that scope can widen to the whole workspace. It says nothing about whether the call is read-only, whether it blocks on LSP startup, latency over large workspaces, or how truncation/limit behaves.

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?

Two tight sentences with the resource first and the usage trigger second — nothing redundant and the key information is front-loaded.

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 output schema means return values need no explanation, and the file-vs-workspace scope default is at least implied. But with five undocumented parameters and no annotations, the description leaves filtering, paging, and line-range behavior unaddressed — too thin for a 5-param tool with zero structured coverage.

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% across 5 optional parameters, and the description compensates only partially: 'for a file or the whole workspace' hints at file_path being optional, but limit, line_start, line_end, and severity are entirely undocumented in both places. An agent cannot tell that severity accepts specific values or that line ranges narrow the scan.

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?

States a specific verb ('retrieve') and resource ('errors, warnings, and code hints') plus the two scopes it supports (a file or the whole workspace). It is clearly distinguishable from siblings like hover or lsp_status, though it never names or contrasts them explicitly.

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?

'Use to check syntax/type errors after edits, before and after refactoring' gives a concrete trigger context, so an agent knows when to reach for it. It stops short of exclusions or naming an alternative (e.g. hover for single-symbol types, lsp_status for server health).

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose that output shape varies materially by direction mode — useful context. However, it never states that this is a read-only, non-mutating inspection, nor anything about language-server availability, failure behavior for invalid positions, or cost.

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?

Two sentences, front-loaded with the purpose, then the mode semantics. Every clause earns its place and there is no boilerplate.

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?

An output schema exists, so return values need not be described. But for a 5-parameter position-based tool with zero annotation coverage and zero schema descriptions, the agent is left without the coordinate conventions or the role of `symbol_name`, which are exactly what the description should supply.

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% across 5 parameters, so the description must compensate and it does not. It only disambiguates `direction` (with its two values); `file_path`, `line`, `character`, and `symbol_name` — including whether line/character are 0- or 1-based, and what `symbol_name` is for when a position is already required — are left completely unexplained.

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 opens with a specific verb and resource: 'Inspect class and interface inheritance hierarchy,' which immediately separates it from get_diagnostics or find_references. It never names a sibling explicitly, so an agent must infer the boundary, but the object of the operation is unambiguous.

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?

It explains the two modes of `direction` ('supertypes' for bases, 'subtypes' for derived), which is genuine usage guidance for the main decision point. It gives no guidance on when to prefer this over find_references or go_to_definition, and no prerequisites such as needing an active language server or an open file.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose what is returned (path, line, column, optional snippet), but does not mention LSP server dependency, behavior when no definition is found, or positional indexing conventions.

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?

Two concise, front-loaded sentences with no filler. The operation and return shape are stated immediately and nothing is wasted.

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?

An output schema exists, but the input schema has no parameter descriptions and there are no annotations. For a five-parameter LSP tool, the description leaves out crucial invocation details such as position indexing and failure behavior.

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% for five parameters. The description does not explain file_path format, whether line and character are zero- or one-based, what symbol_name is for, or what include_snippet controls, so it does not compensate for the schema gap.

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 verb and resource: jump from a symbol position to its declaration/definition. It is clearly distinct from find_references and hover, though it does not explicitly name or contrast siblings.

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?

Usage is implied by 'from a symbol position', but the description gives no explicit when-to-use guidance, no alternatives such as hover or find_references, and no conditions under which this tool should be preferred.

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

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

No annotations are provided, so the description carries the burden. "Inspect" implies a non-mutating read, and the description says what kind of information comes back, but it omits whether a language server must be running, what happens at an invalid or blank position, and whether the result can be empty.

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?

Two sentences, front-loaded with the core purpose and followed by the concrete use case. No filler or repetition.

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?

An output schema exists, so return values needn't be spelled out, and the core action is clear. But with zero annotation coverage and 0% schema description coverage, the unexplained symbol_name parameter and absent preconditions (active LSP, valid position) leave real gaps for a 4-parameter tool.

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 and largely does not. "At a cursor position" loosely maps to line and character, but file_path is unmentioned and the optional symbol_name parameter is completely undocumented, leaving an agent to guess its role relative to the cursor coordinates.

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?

States a specific verb and resource: inspect type definitions, documentation strings, and signatures at a cursor position. This clearly separates it from navigation siblings like go_to_definition or find_references, though it never names those alternatives explicitly.

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?

"Use to check parameter types, return values, and docstrings" gives a concrete use case, so an agent knows when this is the right call. It stops short of stating when NOT to use it or pointing to the navigation siblings as alternatives.

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

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

With no annotations, the description carries the full burden: 'Show status' strongly implies a non-destructive read and the field list tells the agent what information is surfaced. However, it doesn't state whether the call refreshes/starts servers, whether it is cheap or slow, or what happens when no servers are running.

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?

A single front-loaded sentence that puts the action and resource first and then lists the payload contents. Every clause earns its place; nothing is redundant.

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?

An output schema exists, so the description needn't explain return values, and the zero-parameter schema needs no clarification. The only real omission is usage context (when to check status, e.g. after diagnostics failures), which keeps it short of a 5.

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 tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The enumerated fields loosely preview the response shape, which is a small bonus but not parameter semantics.

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 ('Show status') plus a precise resource ('all Language Server processes') and enumerates the reported fields (workspace root, PIDs, restart counts, error summaries). It is clearly distinct from the code-navigation siblings, though it never explicitly says so.

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?

There is no guidance on when to call this tool, no mention of troubleshooting/health-check scenarios, and no reference to alternatives. The agent must infer usage entirely from the tool name and the enumerated fields.

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

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

No annotations are provided, so the description carries the full behavioral burden. "Verifies if the symbol supports call graphs" hints that the result is a support check, but the description says nothing about failure behavior (error vs. negative result), whether an LSP server must be running, whether the file must be open, or whether any state is mutated.

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?

Two tight sentences with the action front-loaded and the verification purpose second. No filler, though the brevity is part of why the parameter and workflow gaps go unaddressed.

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 output schema exists, so return values needn't be explained, but this tool sits in a multi-step workflow with a directly named sibling (`call_hierarchy`) and the description omits that relationship entirely. Combined with zero annotation coverage and zero parameter documentation, an agent has too little to call this correctly.

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% across 4 parameters, so the description must compensate and does not. It implies the symbol is located by position (file_path/line/character) but says nothing about the optional `symbol_name` parameter or why it exists alongside a positional locator, leaving a required-vs-optional ambiguity unexplained.

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?

States a specific verb and resource ("Prepare a function or method for call hierarchy inspection") and adds the precondition being checked ("Verifies if the symbol supports call graphs"). However, it never distinguishes itself from the sibling tool `call_hierarchy` or `get_type_hierarchy`, so an agent cannot tell from the description why both `prepare_call_hierarchy` and `call_hierarchy` exist.

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?

No when-to-use or when-not-to-use guidance. Critically, this appears to be a prerequisite step for `call_hierarchy`, yet the description never says the two are meant to be used in sequence, nor what to do if verification fails. The only implied context is "before inspecting a call graph," which the agent must infer.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that the default is non-writing, that a preview diff is returned, and that actual disk writes require both apply=True and a configuration setting. It does not mention undo behavior or possible conflicts, but the critical safety gating is explicit.

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?

Two compact sentences with no wasted text. The default preview behavior and the write-gating condition are front-loaded and easy to scan.

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 annotations, the description supplies the key operational context: preview-by-default and the apply/writeChanges gate. An output schema exists to cover return values, though the description could say more about coordinate semantics or undo/conflict behavior.

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 explain parameters, but it only covers apply. The required file_path, line, character, and new_name parameters are left to their self-explanatory names, and the optional symbol_name parameter is not mentioned at all.

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 verb and resource: 'Rename a symbol', with clear scope 'across all workspace files via LSP'. It is easy to distinguish from the read-only sibling tools, though it does not explicitly name those alternatives.

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?

It clearly explains the two usage modes: default apply=False returns a preview diff, while apply=True plus writeChanges enabled actually writes changes. It does not need to mention sibling alternatives because this is the only rename operation, but the when-to-use conditions are well specified.

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

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

No annotations are provided, so the description carries the burden; it discloses a useful behavioral comparison (better than text search) but never states that it is a read-only operation, how results are ordered, or how the limit affects output. Given that it is an obviously safe lookup and an output schema exists, this is adequate but thin.

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?

Two short sentences with the core capability front-loaded. The 'much faster and more accurate' sentence earns its place as a selection hint, though it is slightly promotional in tone.

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?

An output schema exists so return values needn't be described, but with 0% schema coverage the description should compensate for the undocumented limit parameter and ideally clarify query syntax (fuzzy, camelCase, regex). It does neither, leaving an agent to guess.

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% and the description mentions neither parameter. 'query' is inferable from 'search', but 'limit' is never explained in schema or description (what it limits, default null behavior), leaving real ambiguity.

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?

States a specific verb (search) and concrete resource types (classes, methods, interfaces, variables) with scope (entire workspace). It implicitly distinguishes itself from document_symbols by scope, though it never names the sibling tool.

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 'faster and more accurate than text search' line implies when to prefer it over textual searching, but there is no explicit when-to-use/when-not guidance and no mention of alternatives like document_symbols or find_references for local or reference-specific lookups.

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