code-context-mcp

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

No annotations are provided, so the description carries the full disclosure burden. It does disclose that results include signatures and lines and are complete from the import graph, but it does not state read-only behavior, permissions, or output structure in detail.

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 short and front-loads the directory export query before the unused-export filter. The second fragment is efficient, though the question-plus-fragment style is slightly less crisp than a direct statement.

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 read-style query tool with no annotations and no output schema, the description gives the core result components: signatures, lines, and completeness from the import graph. It still omits details about output shape and the absolute_paths option.

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 coverage is 33%, so the description must compensate for undocumented parameters. It clarifies dir and the unused flag, but says nothing about the absolute_paths parameter, leaving that behavior partly undocumented.

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 query over a directory's exports and specifically mentions unused exports, so the resource and verb are clear. It does not explicitly distinguish itself from siblings such as who_imports, which is the closest inverse operation.

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 only implied: pass a directory to see its exports, and set unused: true to see unused ones. There is no explicit when-to-use guidance or comparison to alternatives like who_imports or find_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?

With no annotations provided, the description carries the full burden. It implies a read-only lookup and clarifies that the result is a list of files, which is useful, but it does not disclose scope (e.g., workspace-wide search), permissions, or any other behavioral traits.

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 question front-loaded and zero wasted words. The structure immediately conveys purpose and output.

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 simple two-parameter read tool with fully documented schema parameters and no output schema, the description sufficiently explains what it does and what it returns (a list of files). It is nearly complete, though usage context relative to siblings is missing.

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 100%, so both parameters (name and absolute_paths) are already documented in the schema. The description adds no additional parameter meaning beyond naming the symbol concept.

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 (lists) and resource (files that export a function, class, type or constant by name), and frames it as answering 'Where is symbol X defined?'. It is clear, but it does not explicitly distinguish itself from sibling tools like exports_in or who_imports.

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 question 'Where is symbol X defined?' implies the usage scenario, but there is no explicit guidance on when to use this tool versus alternatives such as exports_in or who_imports, and no exclusions or prerequisites are 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?

No annotations are supplied, so the description carries the full behavioral burden, yet it only implies read-only by phrasing. It never mentions the optional diff-gathering behavior (include_changes, change_limit default 3), the source-snippet expansion, or anything about response shape or cost for large files.

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 with zero filler. It is arguably under-specified rather than verbose, but nothing in it wastes space.

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?

Five parameters, no annotations, and no output schema mean the description should explain the optional swings (diffs, snippets, absolute paths) and roughly what comes back. It covers only the core retrieval and leaves the agent to discover the mutation-free but potentially expensive diff path on its own.

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 100%, so all five parameters are documented in the schema itself; that sets the baseline at 3. The description adds nothing about snippet, change_limit, absolute_paths, or include_changes, so no credit above baseline.

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 question enumerates concrete return content (exports with signatures and line numbers, imports, importers), so an agent can tell it is a file-level dependency overview rather than a symbol search. It never names its siblings, though — who_imports and exports_in appear to be subsets of this tool, and the description does not say 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 when-to-use or when-not-to-use guidance and no mention of alternatives. An agent must infer from the phrasing whether this is a bundle of who_imports + exports_in or a distinct operation.

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, and it does disclose what matters: read-only enforcement, hard limits of 50 rows and 8 KB, and which statements are accepted. It does not say what happens when a write statement or oversized result is attempted (error vs truncation), which is the remaining gap.

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?

Nearly every clause earns its place: table catalog, join key, path semantics, two worked examples, and the limits. The single dense block would be more scannable with the schema and the examples separated, but there is little filler.

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 one-parameter free-form query tool with no annotations and no output schema, the definition supplies the schema, join conventions, canonical query patterns, and result limits. The missing piece is how results are returned (column naming, ordering, truncation behavior at the 50-row/8 KB cap).

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 coverage is 100%, so the baseline is 3, but the description goes well beyond by enumerating the actual tables, columns, and *_id join relationships that define the semantic space of the sql string. That catalog is what makes constructing a valid query possible; only the return shape of the result set is left unspecified.

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 names the resource (the code index) and the action (read-only SQL SELECT/PRAGMA), which is specific enough to distinguish it from named operations. It never explicitly contrasts itself with who_imports or exports_in, so an agent could reasonably duplicate those sibling tools with hand-written SQL instead of being routed to them.

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 two example queries ('Who imports X', 'Exports of X') show what the tool can do but not when to prefer it over the dedicated who_imports and exports_in siblings that already exist. Usage is implied (an escape hatch for queries the fixed tools don't cover) rather than 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 zero annotations, the description carries the full burden. It does disclose a real behavioral trait — a hard cap of 25 results — which is useful and not inferable from the schema. However, it says nothing about ordering, whether the cap truncates silently, whether output is paths plus summaries, or whether the call has side effects.

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, front-loaded sentences with no filler; the scope and the exclusion come before the limit. The telegraphic style ("Max 25", with no noun for what is capped) costs it a point on clarity at the margin, but 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?

For a two-parameter read tool with no annotations and no output schema, the essentials (what is matched, what is excluded, result cap) are covered. What an actual result contains, how it is ordered, and how the 25-limit interacts with a broader match set are left unstated, leaving the agent guessing about return shape.

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 coverage is 100%, so the schema already documents both parameters, and the description adds only that matching applies to path or summary (useful, since the schema just says "Text to match"). It says nothing about absolute_paths, but that parameter is already clearly described, so baseline 3 applies.

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 names a specific operation on a specific resource: find files whose path or summary contains given text. It sharpens scope with a negative clause ("Not file contents"), which separates it from content grep, but it never mentions the actual siblings (find_symbol, query, who_imports/exports_in), so an agent must infer which file-oriented 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?

"Not file contents: grep for code" is an explicit when-not paired with an alternative, which is real routing guidance. It stops short of 5 because no sibling tool is named or contrasted, and no prerequisites or preconditions are 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?

No annotations are provided, so the description must carry the behavioral load. It usefully discloses that results come from the import graph (static analysis, not text matching) and that the list is complete, but it omits permissions, performance characteristics, and any caveats about dynamic imports or unresolved paths.

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, front-loaded with the core question, then the return contents and the contrast with grep. No filler.

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?

With no output schema, the description steps in by enumerating what comes back (symbols, lines, re-exports) and framing the result as complete. For a simple two-parameter read tool that is nearly sufficient, with only minor gaps around edge cases.

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 coverage is 100%, so both parameters are already documented, and the description's 'file path or exported symbol' roughly restates the schema's target text. The absolute_paths parameter is never mentioned in the description and gains no extra meaning.

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 question with verb and resource: which files import a given target, derived from the import graph. It explicitly covers both accepted target kinds and distinguishes itself from grep-style searching, so an agent can separate it from siblings like exports_in or search_files.

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 question phrasing plus 'No grep needed' tells the agent this is the go-to tool for reverse-dependency lookup rather than text search. It stops short of naming an alternative tool or stating when-not to use it, so it falls short of a 5.

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