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

With no annotations provided, the description carries the full burden and does so excellently. It discloses deterministic derivation, response size capped independent of repo size, ranked/capped lists, confidence levels with declared vs inferred, known warning types, and staleness detection limitations including the inability to detect uncommitted edits.

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 longer than average but every sentence earns its place. It is front-loaded with a one-sentence summary, followed by explicit usage instructions, output details, and limitations, without redundant 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?

Given the tool's complexity and the absence of annotations, the description covers all necessary context: what it does, when to call it, what it returns, how to interpret results, known edge cases, and relationships to sibling tools. The output schema existence further reduces the need to explain return types, but the description goes beyond that anyway.

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. The description does not add new meaning about the `level` parameter beyond what the schema already says, though it enriches the overall understanding of the response shape (ranked, capped lists) which indirectly informs parameter expectations.

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+resource: 'Get a pre-computed, token-bounded briefing that orients you in an unfamiliar project.' It clearly distinguishes the tool from siblings by explicitly naming atlas_search, atlas_graph, and atlas_index and stating what each is for.

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 explicit when-to-use guidance ('Call this FIRST, once, when you start working on a project you do not already know'), what not to use it for, and names alternative tools for specific tasks. It also warns against repeated calls and notes when the briefing changes.

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, so the description carries the burden. It discloses key behaviors: it composes multiple data layers under a token budget, respects operator config by default, and that an explicit 'full' overrides ATLAS_CONTEXT_OPTIMIZATION. It doesn't cover error modes or resolution-failure behavior, but schema and output schema cover much of the rest.

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 paragraphs, front-loaded with the core purpose, then the primary usage directive, then the response_profile caveat. Every sentence carries information; no filler. Could be marginally tighter but is well structured.

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 tool is a composite context assembler with an output schema, so return values need not be explained. The description covers purpose, when to use, and the config-override behavior. Minor gap: it doesn't mention token-budget or failure behavior when a symbol can't be resolved, but against the rich schema and output schema this is largely adequate.

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 all three parameters including the intent enum values and target resolution semantics. The description adds the meaningful operator-config relationship for response_profile, but does not explain the intent values or target format beyond what the schema provides. Baseline 3 with slight added value.

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 (assemble) and resource (task-oriented context pack) for a symbol or file, and distinguishes itself from siblings by explaining it composes neighborhood, impact radius, tests, and brief layer so the agent doesn't chain atlas_graph/atlas_brief/atlas_search.

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?

Explicitly says to use it first when the target symbol/file is already known, and the response_profile guidance gives concrete when/when-not ('use full only when requested'). It names the alternative workflow (chaining sibling tools) it replaces.

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 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.

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.

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.

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.

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.

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.

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

With no annotations, the description does real work: it discloses that the tool reads a derived artifact ('graph.json') produced by atlas_index and is not a rebuild operation. It does not cover return format or failure modes, but the read-only, derived-data nature is well communicated.

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, no filler. The purpose is front-loaded in the first sentence, with usage and a key boundary condition in the second.

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 tool has 4 parameters, an output schema, full schema coverage, and no annotations; the description covers purpose, usage triggers, and source-data provenance. It leaves minor gaps around cross-mode semantics and return shape, which the output schema partially absorbs.

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 the schema already documents parameter semantics including mode, top_n bounds, and source/target requirements. The description adds little to parameter meaning beyond implying multiple modes, so baseline 3 is appropriate.

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 ('Query') and resource ('the derived knowledge graph') and enumerates the exact operation modes (hubs, paths, neighborhood explanations, reverse-impact radius). It clearly distinguishes itself from atlas_index by noting it reads graph.json rather than rebuilding it.

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?

Explicitly says 'Call this directly when the question is about connectivity, rationale, centrality, or "what breaks if I change this?"' and names the alternative (atlas_index) it should not be conflated with. This gives a clear trigger condition and a boundary.

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 provided, but description fully discloses incremental behavior, skip of unchanged files, async/sync modes, and dry_run behavior. No contradictions.

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?

Well-structured, concise with clear sections. Each sentence adds value; no fluff. Front-loaded with purpose, then usage notes, then behavioral details.

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?

Given four parameters, async behavior, and an output schema, the description covers all necessary context: workflow, behaviors, edge cases (dry_run, full rebuild). Output schema exists, so return values need not be described.

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 already covers all parameters (100% coverage). Description adds value by explaining how parameters affect execution (e.g., dry_run returns candidates, non-empty paths with full=false is synchronous) and usage patterns.

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 clearly states the tool indexes source code and documents into a local search index, using specific verbs and resources. It distinguishes from the sibling tool 'atlas_search' which presumably searches, not indexes.

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?

Explicit guidance on when to use (first time, after staleness) and when not (use dry_run first, ask user). Provides workflow instructions and distinguishes between async and sync execution based on parameters.

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 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.

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.

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.

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.

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.

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.

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

No annotations exist, and the description carries the full burden well: it discloses non-mutation ('Never indexes anything itself'), lock contention ('reindexing'), staleness semantics, watch states with their triggering env vars and failure modes, and index-resolution provenance. These are behavioral traits an agent cannot derive from structured fields.

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 usage guidance is front-loaded and every clause there earns its place, but the Returns section is long and largely restates the output schema — the rubric notes this is unnecessary when an output schema exists. The interpretive notes on 'index_resolution', 'resolution_coverage', and 'watch' add real value, so it is not pure bloat, but the block is disproportionately verbose.

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 enumerated, yet the description is complete: an agent knows exactly when to call it, that it is read-only and side-effect free, and how to interpret the ambiguous fields. Nothing needed to call it correctly 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?

There are zero input parameters, so per the rubric this is a baseline 4; there is nothing for the description to add or omit.

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 ('Get diagnostic metadata and health status of the local vector index') and immediately distinguishes itself from siblings by declaring it is NOT a precondition for atlas_search/atlas_brief and does NOT index, unlike atlas_index.

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?

Gives explicit when-to-use (user asks about health/staleness/indexed repos, or deciding whether to run atlas_index) and explicit when-not (not a precondition for search/brief; call those directly). Alternatives are named with the reason they should be preferred.

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