atlas_graph

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

With no annotations, the description carries the transparency burden. It discloses that the tool reads the derived graph.json produced by atlas_index and does not rebuild the graph, indicating a read-only dependency on a precomputed artifact. This is useful context, though it omits details like staleness or side effects (which are minimal for a read-only query).

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 two sentences long, with the main verb and resource front-loaded. The second sentence adds essential context about when to use and the dependency on atlas_index. Every phrase earns its place with no redundancy or 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 presence of a full output schema and complete parameter descriptions, the description does not need to explain return values or parameter details. It covers the core purpose, usage context, and dependency, which is sufficient for a tool of this complexity. Minor gaps like explicit exclusions or performance notes are not critical because the schema fills in details.

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?

The input schema already provides 100% coverage, with descriptions for every parameter including conditional requirements (e.g., 'Required for path'). The description adds no additional parameter-level information, so it sustains the baseline score of 3 but does not elevate it.

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 queries the derived knowledge graph for hubs, paths, or neighborhood explanations. The verb 'query' and the specific resource ('derived knowledge graph') distinguish it from siblings that operate on raw indices or briefs. It also specifies the graph is derived from atlas_index, providing unique identity.

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 description explicitly says to call this tool when the question concerns connectivity, rationale, or centrality, which gives clear usage context. It also notes it does not rebuild the graph, implying it is for read-only queries. However, it does not explicitly name alternative tools or contrast with them, though the 'call directly' phrase hints at direct selection.

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