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 discloses the output shape (capped previews ~1800 chars for top hits, gists for the rest), that results are budget-fitted, and how to escalate to full text. It does not state permissions, whether the call has side effects (e.g., logging), or behavior on empty/no-match queries, so it falls short of full disclosure.

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 sentences, front-loaded with the core value proposition and the primary routing instruction. Slightly promotional phrasing ("replaces the re-reading tax") costs a bit of density, but nothing is redundant.

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 3-parameter read tool with no annotations and no output schema, the description covers the essential things an agent needs: what comes back, roughly how big it is, and how to get more. Missing only edge-case behavior (no results, errors) and an explicit read-only assurance.

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, but the description adds real meaning beyond the schema: it explains that budget_tokens governs the fitted pack size and that top hits are capped at ~1800 chars while the remainder are gists. The account scoping parameter is left to the schema only.

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: one query returns a compact context pack of memories/files fitted to a token budget. It clearly contrasts with the anti-pattern (re-reading files, scrolling history) and names cairn_read for full text. It does not explicitly distinguish itself from sibling cairn_search, so the differentiation is strong but not complete.

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?

"Call this INSTEAD of re-reading files or scrolling history" gives an explicit selection condition, and "cairn_read returns any node's complete text" supplies the alternative for full fidelity. There is no explicit statement of when NOT to use it (e.g., vs cairn_search or cairn_orient), which keeps it at 4.

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 load and does well: it discloses ordering (newest first), that un-embedded nodes are included, the nightly embedding cycle that gates fetch/search visibility, and the effective result cap (max 60 in schema). It stops short of describing the returned row shape or whether any paging beyond limit exists.

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 sentences, front-loaded with the live-tail/ordering claim, then filters and follow-up. Every clause earns its place — no restating of the name and 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?

For a five-param read tool with no output schema and no annotations, the description supplies the essential mental model (live, unfiltered-by-embedding, newest first) and the escape hatch to cairn_read. Minor gap: nothing about what a returned node row looks like or truncation behavior in the listing itself.

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 five parameters including examples for kind and session prefix. The description only restates the filter dimensions and adds a max_chars tip that actually pertains to the follow-up cairn_read call, so it adds little beyond structured fields.

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: the live tail of the vault, newest-first, covering all node kinds including conversation turns. It explicitly carves out scope against sibling tools (fetch/search can't see un-embedded nodes), so an agent can distinguish it without opening a 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 a clear when-to-use condition ('this is how you see what just happened') and names fetch/search as the alternatives that fail for un-embedded nodes, plus a follow-up path via cairn_read. It does not address cairn_recent, whose name implies overlapping 'newest nodes' semantics, leaving one sibling comparison to inference.

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 it delivers real behavioral context: writes persist across sessions and models, content should not be truncated, transcripts are excluded, and large artifacts should be stored as files with a path reference. It doesn't disclose what a write returns, whether duplicates are deduplicated, or how soon a note becomes searchable, which leaves a gap for a mutation tool.

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, front-loaded with purpose before the usage list and the two capture constraints. Each sentence adds information; a small amount of redundancy between "write the complete salient fact" and "without truncating" keeps it from a 5.

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?

No output schema and no annotations exist to offload anything, and the description never says what a successful call produces or how the note becomes retrievable. It also leaves the `tags` parameter entirely unaddressed, so an agent can call it but not fully exploit 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 description coverage is 0%, so the description must compensate. It gives strong guidance for `text` (complete, untruncated, no transcripts) and implicitly maps `kind` via its list of note categories, but `tags` is never mentioned and no parameter is named or typed. Partial compensation only.

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 concrete verb and resource ("Write a memory to the vault") and frames the scope as ambient capture of durable facts. Every sibling tool (cairn_fetch/search/read/recent/logs) is a read path, so the write-vs-read distinction is unmistakable without needing to name a sibling explicitly.

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 enumerates the triggering cases clearly (decisions, insights, ideas, open items, warnings, procedures discovered while working) and adds a negative rule ("do not paste transcripts — turns are captured separately"). What's missing is an explicit pointer to any alternative tool for the cases this doesn't cover, so it stays below a 5.

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 burden, and it does disclose content composition (compiled digest plus open items) and the call-once cadence. It omits what happens when no prior context exists, whether the digest can be stale, and how large the payload is — meaningful gaps for a context-injection tool.

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 compact sentences with zero waste, and the payoff statement (what you get) is front-loaded before the invocation advice. Nothing repeated from structured fields.

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 zero-param tool with no output schema, the description adequately explains what the returned context consists of. The only real omission is the empty/first-session behavior, which is minor given the simplicity of the 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?

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly signals that no input is required to invoke 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 names a concrete resource — the most recent compiled PROTOCOL digest plus open items — rather than restating the opaque name 'cairn_orient'. It does not explicitly contrast with siblings such as cairn_recent or cairn_fetch, so the agent must infer that this is the session-bootstrap variant from the timing hint alone.

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?

'Call once at the beginning of a session to inherit prior context' gives an explicit trigger and a frequency constraint ('once'). No explicit when-not or named alternative is provided, but the timing cue effectively separates it from cairn_recent and cairn_search.

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 disclosure burden, and it does unusually well: it states the batch cap (up to 8 ids per call), the size budget semantics including the total-body cap (max(60000, this)), and the freshness guarantee that it can read just-written nodes. It does not cover failure behavior, such as what happens with an ambiguous or unknown prefix, which is the remaining 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?

Two densely packed sentences with the core action front-loaded and zero filler; every clause (follow-up role, verbatim layer, prefix matching, batch cap, budget knob, freshness) earns its place.

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 and no annotations, the description still conveys the return nature (verbatim full text, budget-controlled) and invocation constraints. It stops short of describing result ordering or error cases, which is a minor gap for such a simple two-parameter read 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 100%, so the baseline is 3, but the description adds real meaning: 'full ids or unambiguous prefixes' clarifies how ids are matched, 'up to 8 per call' constrains the array, and max_chars is framed as dialing the per-node body budget ('raise it to pull a very long turn whole, lower it to skim').

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 ('Read specific nodes IN FULL by id') and immediately positions itself against siblings, calling itself 'the follow-up to the gists that recent/search/fetch return' and 'the verbatim layer'. An agent can tell it apart from cairn_fetch/cairn_search without opening 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?

Explicitly names when to use it (after getting gists from recent/search/fetch, when the full text is needed) and names the alternatives, plus a distinguishing condition: 'Unlike fetch/search this needs no embeddings, so it reads nodes written moments ago.' Selection logic is fully spelled out.

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, so the description carries the full behavioral burden. It usefully discloses the return shape ('gists', not full text) and a downstream tip about raising max_chars on the read tool. It says nothing about ordering, what 'recent' means (time window), how limit affects scope, or whether the operation is read-only — meaningful gaps for a tool with zero annotation coverage.

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 with the content scope front-loaded and the follow-up action second. The parenthetical about max_chars is slightly muddy since that knob belongs to cairn_read, but the text earns its space overall.

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 read tool with no output schema, the description adequately conveys what comes back (gists) and how to get full text. It falls short on the one structured input (limit) and on the meaning of 'recent', leaving the agent to guess scope and pagination.

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 explain the single parameter, and it never mentions 'limit' or its default of 12. Worse, the only parameter-adjacent advice concerns max_chars, which is not a parameter of this tool at all, which risks confusing the caller about what it can tune here.

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 concrete content set ('recent decisions, open items, and warnings across the vault') and frames it as 'what's live right now', which tells an agent precisely what this returns. It also distinguishes itself from cairn_read by noting it returns gists rather than full text. It lacks an explicit verb (list/retrieve), so it stops just 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?

Usage is implied by 'what's live right now' and it does route the agent onward to cairn_read for full text, which is a genuine alternative named. But it gives no guidance on when to pick this over cairn_search, cairn_orient, or cairn_wander, and no exclusions are 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses the return shape (ids + gists + scores), explicitly flags that results are an index rather than full text, and signals relative cost ("cheap"). It doesn't mention any auth, rate limits, or ranking tunability, which keeps it below 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?

Two sentences, both front-loaded with the highest-value facts (what it returns, how to continue). No filler, and every clause carries actionable 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?

For a simple two-param tool with no output schema, the description adequately covers the return payload (ids/gists/scores), which is the main gap an output schema would otherwise fill. However, the absence of any guidance on `k` or query formulation leaves it only partially complete.

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% and the description explains neither parameter: `query` semantics (syntax, natural language vs keywords) and especially `k` (default 10, no stated meaning or cap) are undocumented. The only param-like mention, max_chars, belongs to a sibling tool, not this 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?

"Ranked hybrid search across the whole vault" gives a specific verb (search) and resource (vault) plus the retrieval strategy (hybrid ranking). It positions itself against cairn_read/cairn_fetch as a downstream step, though it doesn't clarify how it differs from search-adjacent siblings like cairn_wander or cairn_orient.

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 clearly describes the intended workflow (search here, then pass ids to cairn_read, or cairn_fetch for a budgeted pack), which is useful downstream routing. But there is no explicit "when not to use this" or comparison against the other lookup siblings (cairn_recent, cairn_wander, cairn_orient), so the choice among them is left to inference.

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 discloses the core behavior well: graph walking, preference for weak ties, and the kind of adjacent ideas it surfaces. It also explains the return format (gists) and points to cairn_read for full content, though it omits side-effect, permission, and performance details.

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 purpose, then usage, then return behavior. Every sentence contributes useful context, and the follow-up guidance about cairn_read is compact and practical.

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 annotations and no output schema, the description is largely complete: it explains the traversal concept, use cases, and that results are returned as gists. The main remaining gap is the unexplained k parameter, but the overall calling context is otherwise clear.

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 schema describes query and hops, but k is undocumented in both schema and description. The description adds conceptual context around querying and wandering but does not compensate for the missing k semantics, leaving one of three parameters unexplained.

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 resource: it walks the memory graph outward from a query's best hits, favoring weak ties across topic boundaries. It explicitly distinguishes itself from cairn_fetch and from similarity search, so an agent can identify its unique role without inspecting the 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?

It gives clear usage contexts: brainstorming, being stuck, or being asked for fresh angles. It also positions itself as the creative complement to cairn_fetch and contrasts with similarity search, though it does not explicitly state when not to use it.

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