List symbols in one file or search across a project by query and path, returning language-server symbols for navigation, refactoring, or code analysis.
Symbols: of one file (file), or matching a query across the project (query + path).
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | ||
| path | No | ||
| limit | No | ||
| query | No |
Changes observed during successful MCP inspections.
v3.0.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the scope distinction (one file vs. whole project), which is real behavioral context about cost/breadth, but it says nothing about result volume, truncation, or how the limit interacts with project-wide scans.
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 compact sentence with the two modes front-loaded and no filler. It is efficient, though the terse 'Symbols:' fragment reads more like a schema note than a description, which slightly hurts first-glance readability.
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?
This is a 4-parameter tool with 0% schema coverage and no output schema, so the description bears heavy weight. It maps three of four parameters loosely but omits `limit` entirely, leaves `path` ambiguous, and gives no guidance on output shape or choice among the numerous sibling symbol tools.
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 — and it does clarify that `file` selects single-file mode while `query`+`path` drive project search. It still leaves `path` semantics (project root? relative? filter scope?) and `limit` behavior unstated, so the compensation is partial.
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 the resource (symbols) and distinguishes two retrieval modes — single file vs. project-wide query — which is more than a restatement of the name. However, it does not differentiate this tool from close siblings like find_symbol, outline, or repo_map, which appear to overlap in purpose, so an agent still has to guess which symbol tool to pick.
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 parenthetical param pairings (file) vs (query + path) implicitly tell the agent which argument combination triggers which mode, which is useful. But there is no explicit when-to-use guidance relative to the many sibling symbol/search tools, and no statement of exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.