Skip to main content
Glama
LuisCarlosLopes

codesteer-atlas

atlas_expand

Expand compact search refs by chunk ID to retrieve indexed symbol content, follow next_ref for truncated lines, and collect only the evidence needed.

Instructions

Expand compact search references by chunk id — no embedding and no Jev.

Start with only one or two refs, then inspect the response before expanding more. Each additional ref must fill a specific evidence gap. Use three to five only when the task already requires comparing those symbols; never open all hits automatically. Stop when there is enough evidence to answer.

Pass up to five ref values from a compact atlas_search response. Each ref identifies a chunk in the current index (not a historical snapshot). Legacy Base64 references are also supported. If the file changed or the chunk is gone, the item is marked obsolete without returning stale lines. Content comes from the original symbol's indexed line range, including text truncated during indexing. If content_complete is false, pass next_ref to atlas_expand again and concatenate content in content_range order (character offsets, exclusive end). Follow next_ref only if the remaining content is needed; a complete symbol requires all its pages. Continuations are tied to the file hash and need no session cache.

A large class comes back as its header plus outline: the class's methods, each with its own ref and line range. Expand only the methods you need; follow next_ref only if you really need the whole class body.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
refsYesStart with 1–2 search refs; add only needed evidence (hard limit 5).
include_contentNoWhen true (default), include symbol content when it fits the search response budget.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.4.4

TDQS

A4.6/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden and does so richly: obsolete refs are marked without returning stale lines, content_complete=false requires following next_ref and concatenating by character offset, continuations are tied to the file hash and need no session cache, and large classes return a header plus outline.

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?

The purpose and the ref-budget rule are front-loaded and nearly every sentence carries operational weight. It is long, and the next_ref rule is restated once for content pages and again for class outlines, which is mild redundancy rather than padding.

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?

Despite an output schema existing, the description still explains the actionable return semantics (content_complete, next_ref, content_range ordering, obsolete marking, outline) that the agent must branch on. Nothing needed to call this correctly across the pagination and class-outline cases 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 coverage is 100%, so baseline is 3, but the description adds real meaning: refs are limited to five, must come from a compact atlas_search response, identify chunks in the current index rather than a historical snapshot, and legacy Base64 references are accepted. include_content is left to the schema.

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 specific verb and resource: 'Expand compact search references by chunk id,' and immediately contrasts with retrieval modes it is not ('no embedding'). The agent knows this consumes refs produced by atlas_search rather than performing a new search.

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

Usage Guidelines4/5

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

Gives unusually explicit usage discipline: start with one or two refs, inspect before expanding, each ref must fill a specific evidence gap, never open all hits automatically, stop when evidence suffices. It lacks an explicit comparison to sibling tools (atlas_context, atlas_brief), so it stops short of full when/when-not/alternatives coverage.

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