agentic-atlas

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint=false), the description discloses the defining behavior contract: a duplicate, unknown, or roadmap-only id refuses the whole request with the 'batch_not_atomic' error, never returning a partial result. It also reveals the payload composition, the deliberate omission of sections/links/provenance, and the recovery follow-up mechanism, all of which the annotations cannot express. There is no contradiction with the readOnly or idempotent hints.

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 capability sentence is followed by targeted detail on payload composition, atomicity, and the omission/recovery mechanism, with every sentence contributing distinct information. It is longer than the minimum but without filler. The unexplained internal terms 'Hook' and 'sealed' cost it the perfect score.

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 carries the full burden of describing the return payload, and it does: identity fields, Hook, sealed decision-bearing claims with source addresses, and the recovery list. Input constraints, error paths, and follow-up discipline are all covered, leaving only the meaning of 'Hook' undefined. This is sufficient for an agent to select and invoke the tool correctly.

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%, with both ids and expected_revision already well documented, including the cardinality constraint, source examples, and the revision_changed error contract, so the baseline is 3. The description adds only marginal per-parameter meaning, such as the output ordering guarantee ('one ordered Card per id'). The atomic rejection behavior is behavioral context rather than additional parameter semantics.

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 and resource: 'Read 1-4 distinct canonical ids' with an explicit output form, 'one ordered Card per id'. This clearly distinguishes the tool from siblings like atlas_orient or atlas_navigate, which produce or traverse candidate ids rather than consuming them as a minimal payload. The function and scope are unambiguous.

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 caller precondition is stated precisely: 'the lowest sufficient payload for a caller that already holds canonical ids'. The explicit list of omissions, 'sections, relationship links, and expanded provenance are deliberately omitted', signals when not to use this tool, and the recovery-list mechanism promises the exact follow-up call for each omission. It falls just short of 5 because no sibling tool name is named statically in the text.

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?

The annotations already signal read-only, idempotent behavior. The description further explains output shape, ordering, case-insensitive matching, and the important edge case that an empty result is a successful domain miss rather than an error. This adds valuable behavioral context beyond the annotations, though it does still leave some operational details unspecified.

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?

Four short sentences carry all essential information, with the core purpose front-loaded. The statement about routing to atlas_read is placed exactly where it belongs. There is no filler or repetition.

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 still fully describes the output shape and ordering. It covers query filtering, the empty case, and the path to see the full record. Combined with the detailed schema and annotations, the agent has everything needed to invoke and interpret results correctly.

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%, and both parameters already carry rich descriptions in the schema. The tool description adds a couple of clarifications (case-insensitivity, manifest order, empty results) but mostly reinforces what the schema already states rather than providing new semantic content.

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 begins with a specific verb phrase, 'List or search the admitted Decision summaries,' naming the exact resource and scope. It further specifies what each summary contains and explicitly contrasts with atlas_read for complete records, distinguishing it from a sibling.

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 clearly states the effect of providing 'query' versus omitting it, called out as a substring search behavior. It also directly routes the user to atlas_read when a complete record is needed, giving an explicit alternative and the context in which to use it.

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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds significant behavioral context: the semantics of match='exact', 'ambiguous' with its recovery list, and 'none' as a non-error. It also reveals the vocabulary is tied to the active Release's glossary, which is not inferable from annotations alone. No contradictions with annotations.

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 well-structured: it opens with the core purpose, then logically enumerates the three match outcomes and closes with the active Release scope. Every sentence adds necessary detail, and the format is scannable and free of redundancy.

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 lacking an output schema, the description tells the agent exactly what response forms to expect for each input state, including recovery recommendations for ambiguity. Combined with rich schema descriptions and annotations, nothing needed for the first call is omitted.

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 itself documents both parameters well. The description further enriches understanding by explaining how 'term' is matched case-insensitively and how ambiguity is resolved, without duplicating the schema's parameter details. It goes beyond a bare schema by connecting parameter behavior to the overall outcome semantics.

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 uses a specific verb and object ('Define one admitted glossary term') and states the operational scope ('the active Release's own glossary'). It distinguishes the tool from its siblings by detailing three outcomes (exact, ambiguous, none) before any schema is opened. An agent can immediately understand the tool's unique purpose.

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 gives clear behavioral context, including when an exact match, ambiguity, or miss is returned, and that 'none' is a successful miss rather than an error. However, it does not explicitly name alternatives or state conditions under which another tool should be used instead. Sibling differentiation is implied 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?

Annotations already mark this as read-only and idempotent, and the description adds rich behavioral detail: deterministic ordering, per-occurrence direction, bounded pages, cursor validity constraints, and the revision coherence mechanism. It also discloses the errors invalid_argument and revision_changed, which goes well beyond the 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 description is front-loaded with the core purpose and each additional sentence earns its place: ordering, output content, pagination bounds, and filtering constraints are all covered. There is no redundant filler or repetition of schema 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?

For a tool with no output schema, the description compensates well by specifying what each occurrence contains, how pagination works, and what failure signals may appear. Together with the highly descriptive input schema and annotations, the description gives an agent enough context to select and call the tool correctly.

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 documents all parameters at 100% coverage with precise descriptions for bound, cursor, subject, and expected_revision. The description repeats some high-level concepts but does not materially add parameter-level semantics beyond the schema, so the baseline of 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 names a specific verb ('Page'), a specific resource ('one subject's relationship occurrences'), and clarifies it covers inbound and outbound directions. It distinguishes the tool's scope from a generic graph query but does not explicitly contrast it with its siblings like atlas_navigate or atlas_provenance.

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 gives clear invocation context: paginate a subject's relationship occurrences, use cursors for continuation, and do not expect direction filtering. It provides an explicit exclusion ('The page is never direction-filtered'), but it does not name alternative sibling tools or give a when-not-to-use comparison.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds important behavioral detail: the tree is never re-ranked, and a Release with no tour returns path: null as a successful miss rather than an error. This genuinely helps an agent interpret non-standard outcomes correctly.

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?

Every sentence earns its place: the opening identifies the operation, the body clarifies the two views and the null-success edge case, and the closing sentence gives a concrete usage rule. It is detailed without being redundant and front-loads the most important information.

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 zero required parameters and no output schema, the description supplies everything an agent needs: the default view, the output fields, the tour behavior, the special path: null result, and the expected_revision mechanism. There are no obvious invocation-critical gaps.

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 covers both parameters at 100%, including the enum options, the default, and the expected_revision coherence-marker semantics. The description reinforces the view meanings, but parameter-level information is already fully carried by the schema, so the baseline of 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 explicitly states the operation: read the canonical tree or publisher-curated tour, and it clearly maps each resource to its output shape (id, title, position, depth vs. per-step narration). It is specific and self-contained, but it does not explicitly contrast with sibling tools such as atlas_read, so it does not fully meet the sibling-differentiation bar for a 5.

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 an explicit decision rule: 'Use tree for the corpus's whole shape, tour for a guided first reading.' This clearly tells an agent when to pass each view value. It does not, however, state when to prefer atlas_navigate over the other atlas_* siblings or when not to use this tool.

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?

The annotations already declare readOnlyHint=true and idempotentHint=true, and the description meaningfully extends beyond them: match precedence (id over title over Hook), manifest-order tie-breaking, pagination via 'scope' with total/returned/truncated and next_cursor, roadmap candidates' restricted disclosure, and empty-result semantics. No contradiction exists between the description and the annotations — the described behavior is fully read-only and idempotent.

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 front-loaded with a definition, immediately followed by the scoping/usage rule, and then proceeds through matching, ranking, result contents, paging, and edge cases with zero filler or repetition. Every sentence earns its place given the tool's complexity.

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 having no output schema, the description covers the essential return contract: candidate fields (id, status, Hook, disclosure class), roadmap-specific behavior, pagination structure ('scope_cursor', total/returned/truncated), error-adjacent semantics for invalid cursors and revision changes, and the success-with-empty-results case. An agent has everything needed to call and interpret the results of this tool.

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 value beyond the schema by explaining the ranking rule for the query parameter — an id match outranks a title match, which outranks a Hook match — and that an empty query lists all subjects in manifest order, deepening the meaning of the schema's per-parameter text. This is a moderate increment rather than a ceiling-shattering one.

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 opening line states a precise verb and resource: 'Discover canonical identity from an ordinary-language query.' It further distinguishes the tool from siblings by framing it as the entry point for callers without a canonical id and explicitly naming atlas_cards and atlas_read as the tools for callers who already have one. An agent can reliably tell this apart from the sibling tools immediately.

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 gives an explicit condition and routing rule: use this tool when you do not yet hold a canonical id; call atlas_cards or atlas_read directly when you do. It also provides important edge-case guidance such as an empty query listing everything, a no-match query being a successful empty payload, and roadmap candidates being unreadable beyond their name and Hook.

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?

The annotations already mark the tool as read-only, idempotent, and closed-world. The description goes well beyond that by disclosing that the batch is atomic, that invalid addresses cause a 'batch_not_atomic' rejection naming the offending addresses, and that passing 'expected_revision' can trigger a 'revision_changed' error. It also notes the 'separately charged' cost implication, all of which are valuable behavioral facts not available in the schema or annotations.

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 uses three sentences: a crisp one-line summary, a dense but structured enumeration of the returned payload, and a focused note on atomicity and error behavior. It is about as long as it needs to be for an audit tool with no output schema, and the key usage guidance is front-loaded in the first sentence.

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?

There is no output schema, so the description must compensate by explaining what the tool returns; it does so in detail (dependency digest, attestations, distillation id, publisher, date, Release identity fields). It also covers error codes, the atomicity contract, and the only special parameter, making the definition fully contextual for an agent to decide when and how to invoke it.

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 adds meaningful value by explaining what happens if an address is malformed, unadmitted, or uncited (whole batch rejected), and by confirming that 'expected_revision' behaves as a coherence marker that can refuse stale answers. This goes beyond simply repeating the schema descriptions.

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 precise verb ('Expand') and resource ('compact source addresses'), and then specifies exactly what the returned audit facts are. It also establishes a distinct niche by saying 'no ordinary payload carries these facts', distinguishing it from the other atlas tools without ambiguity.

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 gives an explicit usage condition: 'Call it only when auditing how a claim is sourced; no ordinary payload carries these facts.' It does not name alternative sibling tools explicitly, but the 'auditing' prerequisite and the 'no ordinary payload' exclusion provide sufficient guidance for an agent to choose this tool.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is established. The description adds useful behavior: an unrecognized address is refused with 'invalid_argument', confirming rejection semantics. It does not contradict the annotations.

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?

Every sentence earns its place: a one-line purpose, grammar details, error behavior, and usage guidance. The description is information-dense without bloat, and the most important scoping decision is front-loaded.

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 tool with two parameters, 100% schema description coverage, and read-only/idempotent annotations, the description is complete. It covers the address grammar, payload contents, an alternative tool, and an error case. The optional expected_revision semantics are already fully captured in the schema.

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 documents both parameters at 100% coverage, but the description adds further meaning by specifying what each address grammar returns: complete Node, single Section, or complete Decision record. This goes beyond the schema's reasonable baseline without being redundant.

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 first sentence clearly names the operation ('Read') and resource (an address with three accepted grammars), and the body elaborates each grammar's distinct payload. It goes well beyond restating the tool name and even distinguishes this tool from atlas_cards.

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 tells when to use a Section versus a complete Node, and advises that a Card from atlas_cards is usually sufficient and cheaper. This gives an agent actionable decision criteria for choosing this tool over an alternative.

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