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

With no annotations, the description fully carries the burden and does so richly: preservation of existing content, placement to the right, theme-readable styling, group-box placement, connection reference resolution, app-mode side effects (immediate appearance, marked as yours, single Ctrl+Z undo, auto-save), and refusal semantics with error codes (OPEN_IN_APP, ACCESS_OFF, BLOCKED) where nothing is written. This is exactly the atomicity and side-effect disclosure an agent needs.

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 primary operation is front-loaded, but the middle sentence describing app mode ('the cards go to KLYPIX itself while it lets AI tools use it: they appear at once...') is run-on and awkwardly phrased. Dense single-paragraph structure makes the signal harder to extract than it should be.

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 no annotations and no output schema, the description covers mutation semantics, failure behavior, and the return value ('Returns the new card ids'). It is nearly complete for a 3-parameter mutation tool, though permission/auth prerequisites are only implied through app-state error codes.

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 67%. The description adds meaning beyond the schema by explaining that connections may reference new cards by index/title or existing cards by title, and that a card tagged with a group lands in the titled box of that name. It reinforces but does not fully re-document the card 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 (append) and resource (cards and optional connections to an existing v4 .klypix), plus the key distinguishing property that existing items and positions are preserved. This cleanly separates it from create_canvas without needing 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?

Clearly scopes usage to an EXISTING canvas and describes the two operating contexts (app mode when open in KLYPIX on Windows vs. project brains written as files). It does not explicitly name create_canvas as the alternative for new canvases, so the routing signal 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?

With no annotations, the description carries the full burden and does so well: it discloses the semantic-ranking path and its on-device-model dependency, the keyword-only fallback, in-progress brain behavior, inclusion of superseded/archived history with flags, and correction attachment for stale cards. It also clarifies it returns a synthesis context rather than prose — a genuinely non-obvious 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?

The purpose is front-loaded, but the body is a single dense wall of text mixing install instructions, fallback behavior, correction logic, and benchmark statistics ("60 of 102 test questions instead of 55"). Much of it earns its place, yet the measurement asides and install command add length without materially helping tool selection.

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, yet the description describes the return shape (full cards + provenance + lifecycle) and its intended downstream use. Combined with the fallback, lifecycle, and temporal behavior disclosures, an agent has everything needed to call it 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 coverage is 100%, so the baseline is 3, but the description adds real value: it explains as_of semantics beyond the schema's wording and prescribes the "Also: <8–14 words>" suffix on the question to widen recall, which is not derivable from the schema. The k cap and canvas default are already in the schema, so it stops short of a 5.

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 ("Answer a natural-language question from the WHOLE project brain") with concrete example questions, and explicitly distinguishes itself from the sibling search_canvases. An agent can tell what it does and how it differs from keyword lookup without opening 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?

Gives an explicit routing rule: "Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup)." It also names the as_of condition for answering historical questions, so both when-to-use and which-alternative scenarios are covered.

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: it discloses deterministic-only evidence, the meaning of silence, the fact that results are candidates rather than verdicts, that cards from another agent are flagged for coordination, and the dismissal workflow. This is unusually transparent about limits and side behaviors.

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 dense and information-rich, and the key when-to-use guidance is front-loaded. Some phrasing is heavy with parentheticals and jargon, but every clause contributes meaningful behavioral or usage context, so the length is justified.

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 explains what the output means ('Candidates, not verdicts', silence semantics), what evidence counts, what defaults apply, and how to act on results. For a moderately complex decision-support tool, this is complete enough for an agent to invoke it correctly and interpret its results.

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 claim, k, and canvas clearly. The description reinforces their roles—'one concise statement', candidate count, project-brain default—but adds little semantic depth beyond the schema. It earns the baseline 3 rather than more.

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 and resource: it asks the brain to ARGUE BACK against a claim by surfacing deterministic contradictions, standing rules, reversed approaches, and colliding open questions. This clearly distinguishes it from generic brain querying and read tools, and the phrase 'Candidates, not verdicts' further defines its narrow 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?

It explicitly states when to use it: BEFORE committing to a significant decision. It also sets exclusions by warning against mere topical similarity and explaining that silence means 'no deterministic contradiction signal', not verified consistency. It even names the follow-up action and alternative tool relationship: brain_connect with relationship 'not_contradiction' for dismissing confirmed-false pairs.

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 behavioral burden and does so richly: dry run produces a before→projected orphan receipt, apply:true draws 'only additive, removable arrows' and reports a measured after count, and it 'NEVER archives or rewrites cards'. It further discloses that dismissals are logged to a machine-local provenance sidecar with nothing extra written into the brain file — exactly the side-effect detail an agent needs.

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 primary use case (orphan repair) is front-loaded, then scope:'all', then the reconcile-dismissal path — a logical ordering. It is dense and long for a single paragraph, but nearly every clause carries distinct operational information, so little is 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?

For a seven-parameter tool with no output schema and no annotations, the description covers dry-run vs apply semantics, return receipts, side-effect boundaries, scope selection, and the cross-tool dismissal workflow. An agent has everything required to call it correctly without further context.

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 seven parameters and a 3 would be the floor. The description adds genuine meaning beyond it: the 0.55 semantic threshold and its shared-tags + [[mentions]] fallback when the on-device model is absent, plus the permanence of a not_contradiction dismissal. It stops short of covering max/canvas behavior, so not a 5.

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 states a specific verb+resource ('Repairs orphaned decision/milestone cards ... by proposing genuinely related unlinked pairs') and immediately differentiates the two scopes. It also names the sibling tool it complements (brain_reconcile) and the role it plays against it, so an agent can separate it from adjacent graph tools 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?

Explicit when-to-use is given for both modes: scope:'orphans' (default) for repair, scope:'all' for 'deliberate whole-graph densification'. It also states a concrete alternative use case — passing pairs:[{fromId,toId}] with relationship:'not_contradiction' to DISMISS a brain_reconcile false-positive. Nothing about routing 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 does so: it declares read-only, lists the exact side effects (git rev-parse/tag/log/merge-base with fixed argument arrays, and `npm view` only when check_npm is true), and states it creates, edits, and deletes nothing. It also discloses the structuredContent return shape, which is above the bar for a no-annotation 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?

Front-loads the verdict-scope sentence before constraints, and every sentence is substantive. It is a dense single paragraph that could be broken up, but there is little 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 diagnostic tool with no output schema, the description usefully enumerates the returned fields (verdict, layers, version, autoUpdate, supervisors, readinessWarnings, actions) and the layer semantics. Given the large sibling set, a bit more explicit routing versus brain_sync/brain_reconcile would make it fully 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 100% and both parameters are fully documented there (project default, check_npm's network behavior). The description only repeats the check_npm/network point already in the schema, so it adds little new parameter meaning beyond the baseline.

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-only self-check of the installed klypix brain) and enumerates the exact verdict layers (VERSION, CLAUDE, CODEX, TOOLS, SESSIONS, HARNESS). It is easily distinguished from siblings like brain_sync, brain_reconcile, or brain_insights, and it names its CLI twin.

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 triggering question ('is my brain current, correctly installed, in sync, and who is actually live?') and an exclusion ('never recent-chat history'), plus a scope warning not to over-read a clean HARNESS as other hosts working. It does not explicitly contrast against the other brain_* siblings, keeping it short of 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 full burden, and it delivers: it states nothing is deleted, originals are stamped and moved to Archive, an undo exists, apply requires a human approval code the agent never sees, and the repair pass is idempotent and lossless. It also reveals deterministic selection criteria and protected areas.

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 long, but the tool has two modes and five parameters with serious safety constraints. Nearly every clause earns its place, though the opening phrasing is slightly padded and the repair pass paragraph is dense enough that an agent must read carefully.

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 no output schema, the description explains what the dry run returns, what apply produces, how undo works, and what the repair pass does on a second run. For a tool of this complexity, no critical operational detail 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%, but the description adds substantial meaning: apply:true requires syntheses plus an approve code, syntheses titles must match dry-run output exactly, synthesis prose should be 3-6 sentences preserving facts, repair is a separate mode with no approval needed, and the approve code is never shown to the agent. This is far beyond the schema's basic 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 specific operation: consolidate over-grown brain areas by synthesizing dormant cards into one synthesis card, with a separate duplicate-partials repair pass. It clearly distinguishes this from the broader sibling set by defining exactly what it acts on (dormant cards) and what it preserves.

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 when to run it: 'Run it when brain_insights or the brief shows an area has grown noisy.' It also explains the two-phase workflow and when to use the repair pass. It does not name sibling tools as alternatives, but the trigger condition is specific enough to guide selection.

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 only cover openWorld/idempotent/destructive, so the description carries the lifecycle: write creates a 🤝 card the human can see and correct and that the next session picks up at brain_sync; take marks it claimed for peers; done archives the card; continues closes the earlier card as "continued by" this one. It also discloses the scope split between the machine-local automatic layer and the brain-travelling card, which is behavior an agent cannot infer from the schema.

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 tool's identity and the write action, then walks take/done/list in order — every sentence carries routing or lifecycle information. It is dense and long, and the closing "Machine-local for the automatic layer; the card travels with the brain" is terse to the point of ambiguity, but nothing is 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?

For a 16-parameter, four-mode tool with no output schema and thin annotations, the description covers the action surface, triggers, and state transitions well. Minor gaps remain: it does not say how the agent reads the taken work after claiming it, or what happens on an unknown/stale id or session prefix.

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; the description goes further by mapping parameters to actions ("Call {action:"write"} … with the task, what is done, what is NEXT in order, the files and how to verify"), which tells the agent which fields matter per mode. It adds little about id/canvas/project/continues beyond what the schema already states, so it stays below a full 5.

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 the resource (session handoff card) and enumerates four concrete actions — write, take, done, list — each with its own trigger, so an agent can route without opening the schema. It also differentiates itself from siblings by tying the card to brain_sync and session start, which no sibling does.

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 when-to-use for every branch: write when context/usage limit is near, day ends, blocked, or switching tool; take before continuing someone else's work so peers see it is claimed; done on completion; list to see everything open. It also names what to do instead of the anti-pattern ("Never ask the human to paste a summary into the next session — write a handoff").

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 provided, the description carries the burden, and it does well by calling the operation a 'read' and explaining the meaning of the outputs ('load-bearing decisions', 'maybe forgotten', 'aging & unresolved'). It implies read-only behavior and gives interpretive context, though it does not state side effects or limitations explicitly.

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 compact and front-loaded: the first sentence states what the tool reads and what it returns, and the second sentence explains when to use it. No wasted words, and the structure makes the tool easy to grok quickly.

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 read-only inspection tool with three optional parameters and no output schema, the description is nearly complete: it covers outputs, purpose, and timing. It could be more complete by mentioning that this is a read-only operation more explicitly and by addressing how it differs from similar sibling tools, but the core context is sufficient.

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 parameters are already well documented. The description adds some context about 'stale open questions' and 'area sizes', which loosely relates to staleDays and view, but it does not meaningfully enrich the parameter semantics beyond what the schema already provides.

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 identifies a specific action ('Structural read of a brain.klypix') and enumerates concrete outputs: hub cards, orphaned decisions, stale open questions, and area sizes. It is easy to understand what the tool does, but it does not explicitly differentiate itself from sibling tools such as brain_lens or brain_connect.

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 explicit usage contexts: answer 'what matters here / what am I forgetting / what should I review?' and use it at the start of a planning session or before tidying. It does not state when not to use the tool or name alternatives, so it stops short of 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 full burden. It discloses critical behaviors: read-only ('never writes'), that structured=true returns a large payload (tens of KB), and that the default markdown is lightweight. It also explains the conditional data source (KLYPIX vs data twin). Missing auth/rate limits, but for a read-only lens this is strong 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?

The description is one dense, run-on paragraph with nested clauses; the first sentence about KLYPIX conditions is not front-loaded and obscures the tool's main function. It lacks clear structure, making it harder to parse than necessary.

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 six optional parameters and no output schema, the description covers the key facets: the available views, the structured flag's effect, and the default markdown output. It could go further in describing the exact markdown format or the structured object's shape, but it is largely complete for an agent to call it 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining cross-parameter interactions: timeline events are only included for view:'timeline', and structured=true returns the full machine-readable object. It also describes root's role in orrery. This justifies a 4.

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 specifies the resource (brain) and enumerates the views (freshness, provenance, activity, timeline, orrery, unresolved), making it clear what the tool produces. However, it does not differentiate from sibling tools like brain_insights or brain_doctor, and the opening sentence about KLYPIX mixing sourcing conditions muddies the core 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?

It offers example questions ('what's rotting / who wrote this / what happened this week / what's around X / what's undecided') and mentions feeding a UI, which implies usage. But it provides no explicit when-not or alternative tool recommendations, leaving the agent to infer from siblings.

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 so: it discloses the delivery lifecycle (offered into context, later acknowledged, retired by receipt or auto-consumption), 7-day retention, broadcast scoping, and that expiry leaves a failed receipt rather than silent loss. It also states the tool is ephemeral, OS-user-local, and not persisted.

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 action and an illustrative example, and most sentences carry distinct information. It is dense and the receipt/delivery-contract passage is somewhat repetitive, but nothing is padding in the way a vague one-liner would be.

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 complex, unannotated tool with no output schema, the description covers targeting, delivery timing, retention, broadcast scope, receipt semantics, and durability trade-offs — enough for an agent to call it correctly without guessing.

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 semantics beyond the schema: 'all' or omitted reaches only currently-live sessions, a directed id may wait for a not-yet-running session, and delivery timing differs for live vs. quiet recipients.

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 — leave a deliberate, targeted note for another agent session — and immediately contrasts it with brain_note ('durable decision') and brain_message_receipt, so the agent can place it among siblings 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 explicit when-to-use guidance ('if you would otherwise ask the human to relay or paste something... send it here instead'), names the sources for a target id (brain_sync peer list, brain_doctor), and points to brain_reopen for handling queued notes sooner.

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 indicate idempotent and non-destructive behavior. The description adds useful behavioral context by stating the action is a durable receipt and that identity, token, state, lock, and write mismatches fail closed, never silently marking consumption. This goes beyond the annotation fields without contradicting them.

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 dense sentences, each earning its place: the first defines the tool, the second states when to call it, and the third specifies requirements and failure behavior. The critical usage condition is front-loaded and nothing extraneous is included.

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 small, three-parameter receipt tool with no output schema, the description covers what the tool is, when to call it, what inputs are needed, and what happens on mismatch. The annotations cover idempotency and non-destructiveness, so the overall contract is 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 100%, so the baseline is 3. The description mostly restates what the schema already says about message_id and offer_token, though it adds the 'one-time' nature of the offer token and ties the parameters to the fail-closed matching behavior. There is only marginal added meaning beyond 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?

The description identifies a specific operation: confirming that a coordination note was consumed after being offered into context. It clearly distinguishes this receipt/consumption marker from sibling tools like brain_message or brain_note by emphasizing that the note was already offered and acknowledged by a later independent action.

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 precondition: 'Call only after the note has actually been incorporated into the receiving agent's work.' It also states the required inputs, but it does not mention exclusions or explicitly route the agent away from alternative tools.

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 provided, the description carries the full behavioral burden, and it does so thoroughly. It discloses dedup, superseding/resolving/archiving semantics, guard-card firing behavior, the fact that verify instructions are never executed by KLYPIX, evidence fingerprinting caveats, and that question text is stored beside the vector cache rather than on the canvas. This goes far beyond what the schema alone reveals.

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 long but information-dense, front-loading purpose and differentiation before moving into marker semantics and guard behavior. Some material is also present in the schema, but the description uses it to convey operational intent rather than mere definitions. It earns most of its length, though a tighter version could reduce minor 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?

For a high-complexity tool with 9 parameters, nested guard objects, and no output schema, the description covers purpose, usage, lifecycle effects, guard behavior, and side effects well. The main gap is that it does not state what the tool returns or how the agent should interpret the outcome, which is more noticeable because no output schema exists.

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 meaningful semantic context on top of the schema, such as the lifecycle meaning of markers, guard-card triggering, and the distinction between skills and one-time decisions. It does not repeat every parameter definition, which is appropriate given the schema's thoroughness.

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 ('Record something in the project brain ON DEMAND') and a clear resource (the project brain), and explicitly contrasts itself with add_to_canvas as a flat append. The title enumerates the supported note kinds, and the body explains the full decision lifecycle. An agent can tell exactly what this tool 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?

The description gives explicit when-to-use guidance: remember a decision, ask an open question, mark a milestone, log a skill, resolve a finished item, or correct a card. It also names the relevant alternative (add_to_canvas) and states the distinguishing condition ('a flat append' vs routing through the capture engine). Marker-specific guidance further clarifies when to use '+', '✓', and '~'.

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 so: READ-ONLY by default and on every other mode, with the single write exception scoped to modes 'claims' and 'release'; confirms name exact card ids; partial coverage writes '✔ partial' and keeps the card open unless whole:true; a fully-refused call leaves the brain byte-identical; no database or network reads; provenance sidecar records actor/surface/ids. This is unusually thorough disclosure of mutation scope and side effects.

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 'Truth maintenance', but the remainder is a dense, deeply nested run-on of parentheticals and em-dashes that is hard to parse linearly. For a tool this complex some length is justified, yet the structure buries the mode/parameter mapping inside prose rather than organizing it.

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 an 8-parameter tool with no output schema and no annotations, the description covers modes, write scope, edge cases, and follow-up actions well. It partially characterizes returns ('lists committed migration files', echoes 'why' in the receipt) but does not fully describe the shape of findings an agent must act on, leaving a small gap given the absent output 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?

Schema description coverage is 100%, so the baseline is 3, but the prose adds meaning beyond the schema: the correction-cue vs. 'presumed superseded' logic for contradictions, the durability distinction between card-to-card dismissals and raw-commit hints, and the partial-write behavior tied to whole:true. Most per-parameter detail, however, is duplicated in the already-rich 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?

States a specific purpose ('truth maintenance') and enumerates five distinct passes (contradictions, migrations, legacy, release, claims/plans), each with a concrete verb and object. It is immediately distinguishable from siblings like brain_challenge, brain_doctor, and brain_insights, and names the follow-up tools (brain_note, brain_connect) that act on its findings.

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 triggers ('Run it periodically, when recall surfaces something you believe is stale, or right before cutting a release') and prescribes the follow-up actions per finding type: retire via brain_note, dismiss false positives via brain_connect with relationship:"not_contradiction". This is genuine when/when-not routing rather than implied usage.

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 only declare openWorldHint/idempotentHint/destructiveHint; the description adds real behavioral context: the human must approve via an in-chat or native prompt, nothing opens without an answer, nothing runs headless, the session lands in a visible terminal in its own folder, and it is machine-local.

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 default behavior (a waiting note persists up to 7 days) before the action, and every clause carries information. It is dense and the long parenthetical about the prompt mechanism is slightly heavy, but nothing is 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 human-gated, no-output-schema tool it covers prerequisites, the approval flow, and the post-reopen outcome well. The only gap is what the caller gets back on success or failure (e.g., error when the session is running), which is not 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 coverage is 100% and each parameter (start, project, session) is already documented in the schema. The description reinforces the session constraint (must be stopped and have a waiting note) but adds no new syntax or format detail, so the baseline 3 applies.

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: it reopens a specific closed Claude Code or Codex session in a new visible terminal via the host's resume command. It is clearly distinguishable from siblings like brain_note and brain_sync, which queue or route notes rather than revive a session.

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 ('When the human wants it handled sooner, call this') and explicit when-not ('Do not call it again for the same session after the human chose "Not now" unless they bring it up'), plus the precondition that only a session with a waiting note can be reopened.

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 only give the safety profile (idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond that: fail-closed reconciliation that "retains task scope" on invalid evidence, the rule that block overlap is EXACT-PATH plus git merge-tree test-merges, that same-folder overlap is advisory, and that coordination is machine-local and OS-user-local ("a teammate on another machine is invisible"). The scope, failure, and visibility limits are fully disclosed.

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 key action — call first, call on scope change, call before completion — is front-loaded, and the response payload is summarized early. It is information-dense and each clause carries load, though the LIMITS block and lowercase-est clause stacking make it heavier to parse than ideal.

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 an 8-parameter, no-output-schema, nested-object tool, the description supplies the lifecycle, the returned payload, and the hard limits, which is close to complete. It does not cover include_context or the release-lease mechanics in prose (left to the schema), so it is not exhaustive, but 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?

Schema description coverage is 100%, so the schema already documents every parameter, including phase, files, results, releaseClaim, and releaseIntent in depth. The description reinforces a few of these (results is "ONLY for such manifests, never a summary of the work"; phase-based scope replacement), but adds little that the schema does not already state. 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 uses a specific verb and resource — "task gateway" that returns "compact task-relevant brain context, active TASK peers... one-time messages, structured exact-file conflicts, and late-arrival overlap alerts" — so an agent knows precisely what comes back. It is clear and multi-faceted, but it never names a sibling (e.g. brain_reconcile, brain_handoff) to bound it, which is the only thing keeping it 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?

It gives explicit call timing: "Call FIRST with a concise intent and expected files, again when scope changes, and with phase:'complete' before the final response." That is a concrete lifecycle recipe. It stops short of a 5 because it offers no exclusions or named alternatives for when another tool would be preferable.

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 full burden, and it delivers: it discloses that the operation is read-only, that it may declare an experimental MCP Apps UI resource, that no host has been observed rendering it, that the text summary is the verified path, and warns not to promise a visual board. This is unusually transparent about limitations and fallback 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?

The description is dense but every sentence serves a purpose: purpose, return content, UI resource caveat, verified fallback, and usage condition. The important caveat about not promising a visual board is front-and-center rather than buried. No filler is present.

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?

Because there is no output schema, the description appropriately explains what the tool returns: a text summary plus a structured render spec of cards, containers, and connection arrows. It also covers the experimental UI side and the fallback behavior, which 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 coverage is 100% and the single parameter is already described in the schema with its default value. The description reinforces the default but does not add meaningful new parameter semantics beyond what the schema provides, so the baseline score 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 states a specific verb and resource: "Read any .klypix canvas/brain as a SPATIAL BOARD" and clearly distinguishes the tool from a plain query by emphasizing that it returns a spatial render spec, not just content. It also clarifies the default target (project brain), removing ambiguity about what the tool operates on.

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 "Use when the user asks to SEE the canvas/brain/board layout, not just query it," which provides a clear when-to-use boundary. However, it does not name the specific sibling tool to use for pure querying, so the guidance is strong but not as complete as it could be.

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. It discloses a side effect ('save it to the vault') and explains behavioral traits such as groups becoming titled boxes with stacked cards and boxes arranged left-to-right. It doesn't address overwrite behavior or response format, but the creation intent is unambiguous.

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 three sentences, front-loaded with the core operation, then adding user context and layout guidance. Every sentence contributes distinct information, and there is no repetition of schema field names or annotation data.

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 creation tool with no output schema and five parameters, the description covers the main behavioral choice (groups vs loose grid), persistence, and the intended user experience. It omits return value and error/overwrite behavior, but those are secondary for a create operation and the input schema already documents all parameters.

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 value beyond the schema by advising card style ('Prefer short, titled cards (one idea each) connected by meaningful arrows') and by explaining the semantic difference between grouped and ungrouped cards, which maps to the `groups`, `group`, and `connections` 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?

The description opens with a specific verb and resource: 'Create a new .klypix canvas from cards + connections and save it to the vault.' It clearly distinguishes this from siblings like add_to_canvas by emphasizing 'new' and 'save it to the vault,' and adds user context via 'The user opens it in the KLYPIX app (Canvas → Open).'

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 provides concrete guidance on when to use groups versus the loose grid: 'For anything a person reads IN ORDER — steps, phases, checklists, sections — put the cards in groups.' It explains the consequence of not grouping: 'the loose grid follows arrows, not reading order, and scatters a sequence.' It doesn't explicitly name alternative tools, but the 'new' vs add distinction is clear enough.

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, idempotentHint, and openWorldHint=false, so the safety profile is covered. Beyond that the description discloses non-obvious behavior: it reports app-running state, per-feature prerequisites 'what each still needs from the user,' current front canvas and card selection, view state, and a daily quota ('how many Gemini readings this tool has left today') — real rate-limit context the annotations do not carry.

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 call trigger are front-loaded in the first two sentences, and each clause adds a distinct capability rather than repeating the schema. It is dense and long — one enumerative sentence about return state would read better as a list — but no sentence is pure 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?

With no output schema and no parameters, the description must carry the full burden of what comes back, and it does enumerate the returned facts (running state, canvases, view, selection, quota). Combined with the call-timing guidance, an agent has enough to invoke and interpret it correctly, though return formats/types remain undefined.

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 the baseline of 4 applies and there are no parameter semantics to mis-specify. Nothing in the description contradicts the empty 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 ('Check what KLYPIX can do for the user on this PC right now') and enumerates the concrete facts returned: app running state, open canvases, save location, and available features. It also distinguishes itself from siblings by routing selected card ids to read_card_contents, so an agent can tell it apart from other status/canvas tools.

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 an explicit call condition: 'Call it before promising anything that needs the KLYPIX app,' which is a clear when-to-use trigger. It does not state when NOT to call or name a competing status tool, but the preflight framing is strong enough to guide selection.

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 provided, the description carries the full burden of behavioral disclosure. It transparently states the scope ('all .klypix / .any canvas files in the vault') and the included output details ('card and connection counts'). 'List' clearly implies a read-only, non-mutating operation.

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 fully captures what the tool does without any filler or redundant phrasing. Every word contributes meaning: 'List all', the file types, the vault scope, and the counts.

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-parameter listing tool with no output schema, the description is complete: it specifies what files are listed, the scope, and the key output contents. There are no missing details that would prevent an agent from selecting and invoking this 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 tool has zero parameters, so the baseline is 4. The description appropriately focuses on the tool's behavior rather than parameters, and no parameter explanation is needed because the input schema is empty.

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 a specific verb ('List'), a specific resource ('all .klypix / .any canvas files in the vault'), and the expected output ('with card and connection counts'). It is easily distinguishable from sibling tools like read_canvas or create_canvas, though it does not explicitly name alternatives or contrast with search_canvases.

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 implies when to use this tool: whenever an agent needs a full inventory of canvas files in the vault. However, it does not explicitly mention when not to use it or describe how it differs from search_canvases, so the usage guidance is only implicit rather than explicit.

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 provide idempotentHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds valuable non-obvious behavioral details beyond annotations: KLYPIX never installs or runs Graphify, never copies graph nodes into brain.klypix, degrade-to-brain-only fallback, project-root confinement, and that deep_history may cold-load a local model. A 5 would require more detail about output shape or failure modes; a 4 fits.

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 dense but organized: purpose first, then key behaviors, fallback, constraints, and the deep_history caveat. Each sentence adds real value. It loses one point because some deep_history detail is repeated from the schema description, but overall it is efficiently 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?

Given the tool's 8 parameters, 100% schema coverage, annotations for idempotency/destructiveness, and no output schema, the description covers the critical missing context: what the combined context contains, source fallback behavior, project-root safety rules, model-loading performance trap, and graceful degradation. An agent has enough to invoke it correctly without surprises.

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 every parameter is already well-documented in the schema. The description reinforces deep_history's tradeoff and the root-escape restriction, but it does not need to add full param semantics because the schema carries that weight. 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 ('queries') and a clear resource ('combined read-only context' from project graph plus KLYPIX brain cards). It distinguishes itself from the many brain/canvas siblings by describing its provider-neutral graph source and correction-aware brain cards. An agent can understand exactly what this tool returns and how it differs from related read tools.

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 explicit when-to-use guidance for deep_history ('only when superseded history is genuinely needed') and explains the default avoids loading the local embedding model. It also states boundary conditions: source-file anchors are accepted only inside the project root, and missing graph artifacts degrade cleanly to brain-only context. This is concrete and actionable.

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 annotations (idempotent, non-destructive, not open-world), the description meaningfully expands behavioral transparency: it explicitly says 'Nothing is written,' explains that a 'missing' file may simply be absent from the current checkout, covers rename-candidate detection, and clarifies that slash-joined enumerations and other-project paths are skipped. This gives the agent nuanced expectations beyond the structured 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?

The description is dense and front-loaded with the core 'Read-only drift check' intent. Every sentence carries useful behavioral information, but the writing is somewhat verbose, especially around the branch divergence explanation and the 'fix cards' note. It is well-structured for a complex tool but not maximally concise.

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?

Without an output schema, the description does a good job explaining what the tool reports: missing/moved files, rename candidates, and branch divergence status. It also covers edge cases like other-project paths and checkout-local absence. The main gap is the lack of explicit detail about the return format or how the report is delivered, but the description covers the essential context for correct invocation.

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 does not add significant parameter-level detail beyond what the schema already provides; it only restates the default behavior contextually. Since the schema already documents both optional parameters and their defaults, no additional compensation is needed.

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 'Read-only drift check' and precisely defines the operation: verify brain card file references against the working tree and report missing/moved files plus branch divergence. This clearly identifies the tool's resource and purpose, and differentiates it from sibling tools like project_map_scan or brain_reconcile by focusing on drift detection rather than scanning or reasoning.

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 strongly implies when to use the tool—when you need to check whether brain card file references are still valid in the repo—but it does not explicitly state when not to use it or name alternative tools. Sibling context suggests related tools exist, but no direct comparison or exclusion is provided, so usage guidance is implied rather than explicit.

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?

Even with annotations already marking idempotentHint=true and destructiveHint=false, the description adds concrete behavioral detail: it walks the repo gitignore-aware, excludes junk dirs, resolves import aliases/workspaces, writes exactly one file, and does not build a per-symbol AST graph. No contradiction 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?

Three sentences front-load the core behavior and each adds useful context (scan scope, output file, downstream usage, limitation). Minor brand language ('KLYPIX's own') and the somewhat vague 'through the same door' phrase keep it from a 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?

For a one-parameter tool with no output schema, the description covers the input, traversal behavior, exclusions, resolution rules, the write side effect, and the relationship to project_map_context and deeper artifacts. An agent has enough information to call and interpret the result.

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 parameter is already fully documented in the schema ('Absolute project root. Defaults to this MCP connection's configured project/vault'), and schema coverage is 100%, so the baseline is 3. The description doesn't add parameter-specific meaning beyond 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?

The description opens with a specific verb ('scanner'), names the resource ('repo', 'JS/TS family'), and clearly states the output ('writes klypix-map/graph.json'). It also distinguishes itself from deeper AST-graph artifacts, so an agent can tell it apart from siblings like project_map_context.

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 states the tool is the zero-install native scanner and explains that the artifact serves project_map_context automatically when no Graphify artifact exists. It also notes the tool deliberately avoids per-symbol AST graphs, implying an alternative for deeper analysis, though it does not explicitly name sibling tools or give when-not-to-use instructions.

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 disclosure burden and does so well: it states that the live read includes unsaved changes and the person's view state, that images are capped at 4 per answer with downscaling and named exclusions, that lock-protected cards are omitted with a count reported, and it warns that card text is data rather than instructions (prompt-injection defense).

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 mode-dependent behavior is front-loaded, but the body is a dense run-on of parentheticals, em-dashes and ALL-CAPS emphasis that is hard to parse in one pass. Several clauses (photo sizing rationale, 'Inside:' line) are useful but could be tightened without losing meaning.

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 only one parameter, the description fully specifies what comes back: every card with id, the connection graph, wikilinks, tags, status, comments, saved link/video/photo readings, attached images with labels, and how locked cards are reported. Nothing essential for correct invocation 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% and the schema already documents the accepted forms (title, filename, path). The description largely restates the same accepted identifiers ("Pass the canvas TITLE as KLYPIX shows it... a filename, vault-relative path, or absolute path also work"), adding little beyond the schema, so baseline 3 applies.

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 and resource ('read a canvas') and distinguishes two operating modes (live when KLYPIX is open vs. structured markdown otherwise). It also differentiates itself from the sibling read_card_contents by scoping itself to the canvas level and routing card interiors elsewhere.

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 tells the agent it does NOT need to list or search first, and directs card contents to read_card_contents with the ids printed here. It does not, however, contrast itself with other canvas-related siblings such as canvas_view or list_canvases, so the alternative-selection guidance is strong but not exhaustive.

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?

Far exceeds the annotations: it discloses cost attribution (paid_by), per-tool quota (at most 20/day), caching (saved readings return instantly and spend nothing, refresh:true forces new), side effects (new readings pinned beside cards, one Ctrl+Z removes them), a ~40s latency contract returning still_reading with retry_after_seconds, and that content is fenced as data, never instructions. readOnlyHint=false is consistent with the pinning behavior described.

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?

It is front-loaded and most sentences carry load-bearing behavior, but it is a single ~250-word run-on dense with parentheticals, and a few asides ('the way its Read contents does', 'Authors are what each card records, unverified') add bulk without changing agent behavior. Splitting mode/return/limits into distinct sentences would help.

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 carries the full return-format burden and does so: it explains the saved-vs-app-mode answer, fencing and provenance marking, full/partial status, embedded files resolved as text/image/local path, and the 'Tell the user' relay sentence for unreadable cards. Nothing an agent needs to invoke or interpret the call 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 already 100%, so the baseline is 3, but the description adds real meaning: max_chars caps the whole answer at 48,000 (not just per card), card_ids must be the ids read_canvas prints, entry_paths must be paths from the folder's own listing, and pin_result/wait_seconds are inert when reading saved files. These clarify cross-parameter interaction beyond 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?

The opening states a specific verb and resource ('Read what is INSIDE cards on a KLYPIX canvas') and immediately enumerates the card types it covers (reel, YouTube video, web page, media, PDF/Office, text, folder). It also routes the agent by naming where the ids come from (read_canvas, klypix_status), distinguishing it from those siblings.

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 concrete selection rules: pass up to 5 card ids as read_canvas prints them, or the ids klypix_status lists to read the current selection; use refresh:true for a new reading; use entry_paths for folder cards. What is missing is an explicit when-not/alternative statement (e.g. use read_canvas or canvas_view instead when you only need structure).

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 provided, the description carries the full behavioral burden and does so thoroughly. It discloses ranking is lexical, semantic only when an optional local model is installed, degrades cleanly without errors, explains time-travel semantics for as_of, and clarifies registry population.

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 dense but efficient, with the core scope and usage front-loaded. It is one long sentence with many embedded caveats, but every clause conveys necessary constraint information and no filler exists.

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, the description covers almost all critical call guidance: ranking, semantic fallback, error behavior, as_of semantics, and registry prerequisites. The only notable gap is the absence of any return-value or result-shape description, though no output schema exists to offset this.

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 meaningful semantic detail: it explains that as_of treats superseded cards as live if current at that date and clarifies the scope of query across all registered project brains. This goes beyond the schema's simple field 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?

States a specific verb and resource: cross-project memory search across every registered brain.klypix. It explicitly contrasts with the current vault and clearly differentiates from sibling search tools like search_canvases.

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?

Provides a clear usage context: 'Use when the answer may live in ANOTHER project's decisions.' It also describes a key limitation (projects absent from the registry are unreachable), which helps avoid misuse. However, it does not name alternative sibling tools or give explicit when-not-to-use guidance.

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. It usefully discloses that locked boxes are never searched and that results include canvases and matching cards with ids and dates, but omits permissions, pagination, and read-only status (though 'Search' implies it).

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: search scope, return shape, exclusion. It is front-loaded and every sentence adds distinct information with 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 one-parameter read tool with no output schema or annotations, the description supplies search scope, return content, and an important exclusion. It could still clarify query syntax and pagination, but it is largely 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 coverage is 100% and the query parameter is already described as text or #tag. The description adds value by listing what can be matched (card text, titles, #tags, KLYPIX labels, readings), clarifying the parameter's scope beyond 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 (Search) and resource (canvases) and enumerates searchable content (card text, titles, #tags, KLYPIX labels, readings) across every canvas. The scope 'every canvas in the vault' distinguishes it from read_canvas and list_canvases even without naming those siblings.

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?

Implies usage by describing cross-canvas search of card content, but never states when to choose this over search_all_brains or read_canvas, nor any exclusions. Guidance is inferred rather than explicit.

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