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

With no annotations, the description carries the full burden of behavioral disclosure. It describes the return content, which is helpful, but it does not state that the operation is read-only, whether it has side effects, or any authorization requirements. For a tool with zero annotation coverage, this is a significant gap.

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 a single sentence with zero waste, front-loading the primary usage directive and then listing the returned information. Colons and dashes provide clear structure without verbosity.

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 simple one-parameter read tool with no output schema, the description adequately explains what the tool does and what it returns. It is nearly complete, but it could add a note that the operation is safe or read-only to fully reassure an agent given the lack of annotations.

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 0%, so the description must compensate. It says 'given an absolute or relative file path', which clarifies the parameter's expected value beyond the schema's bare 'File Path' title. However, it adds little else (e.g., no constraints on existence or format), so it only partially compensates.

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 ('returns what the brain knows') and resource ('given a ... file path'), and enumerates the returned content (matching node, code neighbors, linked vault pages, access events). It does not explicitly contrast with sibling tools like brain_search or brain_node, but the purpose is clear enough for an agent to distinguish 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?

It explicitly says 'THE tool to call before touching a file', giving a clear context for when to use it. However, it does not name alternatives or state when not to use it, leaving some inference to the agent.

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 carries the full burden and does disclose two useful traits: BFS traversal order and a hard 50-result cap (truncation behavior). It omits error/edge-case behavior (missing node, depth limits) and whether the cap silently truncates or errors.

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 short sentences with zero filler, and the core operation is front-loaded ahead of the supplementary cross-layer note. Not padded, though slightly terse for a 0%-coverage schema.

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 described, and the description covers traversal semantics and the result cap. For a simple two-parameter read tool this is nearly complete, with only usage routing and node_id semantics 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 0%, so the description must compensate. It clarifies that `depth` means hop count, adding real meaning beyond the bare integer schema, but says nothing about `node_id` format/naming or acceptable depth ranges, leaving the required parameter undocumented.

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 operation (retrieve neighbors of a node) with the traversal method (BFS) and result cap (max 50). The resource is clear, but it does not distinguish itself from siblings like brain_path or brain_context, which may also traverse graph structure.

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?

No explicit when-to-use guidance or alternatives are given. An agent must infer that this is for local neighborhood exploration rather than path-finding (brain_path) or global search (brain_search), but the description never says so.

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. 'Get' implies a read, but it says nothing about behavior on a missing id, permission requirements, lookup cost, or how large 'full details' is. For a zero-annotation tool this is a significant gap.

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 sentence with the verb, resource, keying constraint, and format examples; no 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?

A one-parameter read tool with no output schema, so the description should at least sketch what 'full details' returns. It names the resource and id format but leaves the return shape and error behavior unstated, which is a modest but real gap.

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 0% and node_id has no schema description, so the description's two example ids ('vault:api-agent-allowlist', 'api:src/server/routes.py') are genuinely useful for inferring the id format. It still doesn't explain the namespace/prefix scheme or what happens with a malformed id, so it only partially compensates.

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 ('Get full details') and resource ('brain node') scoped to a lookup by id, which clearly separates it from the sibling brain_search. It does not, however, explicitly contrast itself against brain_neighbors or brain_path, which also operate on nodes.

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 phrase 'by id' implies you must already know the node id, but the description never states when to use this instead of brain_search (e.g. 'use brain_search when you don't have an id'). No prerequisites or exclusions are given.

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 carries the full burden, but 'BFS over all edge types' is a genuinely useful disclosure — it tells the agent paths are unweighted and that every relationship type is traversable. It omits what happens when no path exists, whether traversal is directed, and any cost or depth limits.

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?

One front-loaded sentence with the resource, the operation, and the algorithm; nothing wasted.

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 explained. Still, for a pathfinding tool with zero parameter documentation and no annotations, the absence of no-path/error behavior and directedness leaves real 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?

Schema coverage is 0% and the properties are bare strings, so the description is the only source of meaning. 'Two brain nodes' implies from_id/to_id are node identifiers, but no format, ID source, or error behavior for invalid IDs is given.

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+resource ('shortest path between two brain nodes') and even names the algorithm, so an agent knows exactly what it computes. It does not differentiate itself from siblings like brain_neighbors or brain_context, which could also traverse graph relationships.

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?

No guidance on when this is preferable to brain_neighbors, brain_search, or brain_context. The algorithm note hints at the use case (unweighted reachability) but the agent must infer all routing decisions.

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 supplied, so the description carries full behavioral burden, yet it says nothing about ranking, result limits, permissions, or behavior on empty/no-match queries. It only names the corpora searched, which is a scoping statement rather than a behavioral trait.

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?

One tight sentence with no filler, and the scope (the three corpora) is front-loaded after the verb. It is efficient, though the unexplained "ASM" term adds ambiguity rather than value.

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 described. But with no annotations and no usage context, the description leaves the search semantics and the read-only nature implicit; adequate for a one-parameter search, but with clear 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 single query parameter has 0% schema description coverage and the description does not compensate — it never explains whether the query is free text, a keyword list, a regex, or a structured expression. Meaning beyond the schema is absent.

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 clear verb+resource ("Search ASM") and enumerates three target corpora, which hints at scope. However, "ASM" is unexplained jargon and the description does nothing to differentiate this tool from siblings like memory_recent or brain_context, leaving the agent to guess at the distinction.

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?

No when-to-use guidance is provided, no exclusions, and no alternatives named despite six closely related sibling tools. The agent cannot tell from the text when brain_search should be preferred over memory_recent or brain_context.

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 carries the full burden and does reasonably well: it discloses the cross-agent scope ('from any agent'), the brief return shape, and the OR-style matching semantics ('any word may match'). It omits ordering guarantee beyond 'newest' and pagination behavior.

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 tight sentences, front-loaded with the resource and scope, then filtering semantics, then the escalation path. The return-fields list is slightly enumerative but each item carries 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?

An output schema exists so return structure needn't be spelled out, yet the description still gives a useful preview and routes to brain_node for full records. The only real gap is `limit` semantics, which is minor for a read-only list 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 coverage is 0%, so the description must compensate. It explains `query` well (word-based, any-word matching) but says nothing about `limit`, leaving one of two parameters undocumented. Partial compensation.

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+resource ('Newest shared records from any agent, in brief form') and distinguishes itself from the full-record path by naming brain_node for the detail view. It does not explicitly separate itself from close siblings like memory_record or brain_search, so it stops short of 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?

Implied use case is clear (list the newest brief records, optionally filtered), and it points to brain_node('memory:<id>') as the alternative when a full record is needed. No explicit when-not guidance or comparison against brain_search/memory_record.

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 carries the full burden and largely delivers: it explains that `supersedes` targets stop surfacing in search/recall but remain readable by id, that credentials/card numbers are mechanically redacted, that `resolves`/`corrects` are written to a lifecycle ledger, and what the response contains (`thread_ids`). It omits permissions, reversibility, and any failure/conflict behavior, so not a 5.

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?

Front-loaded with the core action before the detail, and each sentence carries distinct information about a distinct parameter or behavior. It is dense and somewhat long, but there is little filler; backticked parameter names aid scanning.

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 10-parameter mutation tool with no annotations and no output schema, the description explains response `thread_ids` reasonably well, but five parameters (files, decisions, open_threads, agent, session_id) receive no guidance at all, and there is no mention of permissions or conflict behavior. Adequate but with clear 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?

Schema description coverage is 0%, so the description must compensate. It richly documents `summary` (one line, ≤500 chars), `details`, `supersedes`, `resolves` (including the `<record-id>#<n>`, record-id, and `vault:<id>` forms), and `corrects` (with a target/claimed/truth/evidence shape), but leaves `agent`, `files`, `session_id`, `decisions`, and `open_threads` entirely undocumented — half the parameters.

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 — persist a completed unit of work into ASM memory and the Obsidian daily log — and the trigger ('Call after changing files'). Clearly distinguished from the read-side siblings (brain_search, memory_recent) without needing to open any schema.

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 context for use ('call after changing files') plus content rules: record concrete outcomes and unresolved work, never secrets/credentials/raw transcripts/unverified claims. It stops short of naming alternatives or exclusions (e.g., when to prefer memory_recent or brain_search), so it is clear but not fully routing.

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