Skip to main content
Glama
LuisCarlosLopes

codesteer-atlas

by LuisCarlosLopes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

atlas_search

Search code and documents in a project's local index using semantic and keyword queries to find exact symbols or concepts before broad file reads.

Instructions

Search code AND documents in the project's local index — your FIRST tool to find, explore or investigate anything here, before broad file reads or grep.

Runs a semantic hybrid search (vector + BM25, fused via RRF) over pre-indexed chunks of source code (classes/functions/methods) and documents (Markdown, text, JSON/YAML/ TOML). Pass natural language or exact symbols. To get your bearings in an unfamiliar project first, use atlas_brief.

Token-efficient two-pass pattern: by default this returns metadata only (file_path, lines, symbol, type, score). Locate first, then read the exact lines with Read, or re-call with include_content=true for the few results whose content you actually need.

Call directly — do NOT call atlas_status first "just to check". If the index does not exist yet, this raises an actionable error explaining how to build it (see atlas_index).

Omit response_profile to respect the operator configuration. Do not select "full" routinely: it overrides ATLAS_CONTEXT_OPTIMIZATION even when enabled. Start with metadata and expand only symbols needed to close an evidence gap. Start with only one or two directly relevant symbols; inspect their contents before expanding helpers, types or additional results. Do not expand every search hit automatically. Stop when the task has sufficient evidence. Use atlas_expand(refs) for omitted content; use "full" only when explicitly requested or when fields omitted by the compact format are required.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
repoNoOptional repository name filter.
limitNoAlias for 'top_k'; overrides it when provided.
queryYesNatural language description or exact symbols to find.
top_kNoMax results, 1-50. Defaults to 5.
languageNoOptional language filter (e.g. 'python', 'javascript', 'go').
structuralNoWhen true, adds a graph spreading-activation arm to the RRF fusion for this call only. Defaults to false (opt-in; does not change default ranking).
path_prefixNoOptional path prefix filter (e.g. 'src/controllers').
include_contentNoWhen true, includes each result's 'content'. Defaults to false (metadata/location only) to save tokens. Compact profile never turns content on.
response_profileNo`default` follows ATLAS_CONTEXT_OPTIMIZATION; `full` keeps the current delivery format; `compact` applies deterministic compaction and, when ATLAS_RELEVANCE is on, Jev's top_k cut (or the conservative selection with ATLAS_RELEVANCE_CUT=0).default

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.4.4
    • changedInput schema / properties / include_content / description
      Previous value: -"When true, includes each result's 'content'. Defaults to false\n(metadata/location only) to save tokens."New value: +"When true, includes each result's 'content'. Defaults to false\n(metadata/location only) to save tokens. Compact profile never turns content on."
    • addedInput schema / properties / response_profile
      Added value: +{
+  "default": "default",
+  "description": "`default` follows ATLAS_CONTEXT_OPTIMIZATION; `full` keeps the\ncurrent delivery format; `compact` applies deterministic compaction and,\nwhen ATLAS_RELEVANCE is on, Jev's top_k cut (or the conservative selection\nwith ATLAS_RELEVANCE_CUT=0).",
+  "type": "string"
+}
    • addedInput schema / properties / structural
      Added value: +{
+  "default": false,
+  "description": "When true, adds a graph spreading-activation arm to the RRF fusion\nfor this call only. Defaults to false (opt-in; does not change default ranking).",
+  "type": "boolean"
+}
  2. Changed8 schema fields changedv1.4.2
    • changedInput schema / properties / include_content / default
      Previous value: -trueNew value: +false
    • changedInput schema / properties / include_content / description
      Previous value: -"When false, omits the 'content' field from results to save tokens,\nreturning only metadata and location (file_path, lines, symbol, type, language, score).\nDefaults to true."New value: +"When true, includes each result's 'content'. Defaults to false\n(metadata/location only) to save tokens."
    • changedInput schema / properties / language / description
      Previous value: -"Optional programming language to filter results (e.g., 'python', 'javascript', 'go')."New value: +"Optional language filter (e.g. 'python', 'javascript', 'go')."
    • addedInput schema / properties / limit
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alias for 'top_k'; overrides it when provided."
+}
    • changedInput schema / properties / path_prefix / description
      Previous value: -"Optional file path prefix to restrict the search to a specific directory (e.g., 'src/controllers')."New value: +"Optional path prefix filter (e.g. 'src/controllers')."
    • changedInput schema / properties / query / description
      Previous value: -"The natural language search term or description of the code to find."New value: +"Natural language description or exact symbols to find."
    • changedInput schema / properties / repo / description
      Previous value: -"Optional repository name to filter results."New value: +"Optional repository name filter."
    • changedInput schema / properties / top_k / description
      Previous value: -"Maximum number of results to return (integer between 1 and 50). Defaults to 5."New value: +"Max results, 1-50. Defaults to 5."
  3. First observedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations present, the description carries the full burden and does so well: it discloses the default metadata-only return shape (file_path, lines, symbol, type, score), the token-efficiency rationale, the actionable-error behavior when no index exists, and how response_profile interacts with ATLAS_CONTEXT_OPTIMIZATION and ATLAS_RELEVANCE.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, primary directive and the two-pass pattern are front-loaded, and most sentences earn their place. The tail repeats itself, however: 'Start with only one or two directly relevant symbols... before expanding helpers' largely restates 'Do not expand every search hit automatically. Stop when the task has sufficient evidence.'

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 no explanation. For a 9-parameter tool the description still covers when to use it, the recommended call sequence, token trade-offs, config overrides, and failure behavior — nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description adds genuine operational meaning on top, e.g. 'Omit response_profile to respect the operator configuration' and 'Do not select full routinely', plus the guidance that compact never turns content on. It adds behavioral intent for include_content and response_profile rather than repeating the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource ('Search code AND documents in the project's local index') and even names the mechanism (semantic hybrid search: vector + BM25 fused via RRF) over pre-indexed code chunks and docs. It distinguishes itself from siblings by naming atlas_brief, atlas_expand, atlas_status and atlas_index by role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions itself as the FIRST tool to use 'before broad file reads or grep', names atlas_brief for orientation in unfamiliar projects, and tells the agent NOT to call atlas_status first. It also prescribes the two-pass workflow (locate with metadata, then Read or re-call with include_content).

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

Deploy Server

Other Tools