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 meaningful detail: preserving all existing items and positions, placing new cards to the right, and defining how connections can reference new or existing cards. It does not cover error behavior or permissions, but the core side effects are well 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?

Two tight sentences, front-loaded with the action and the most important guarantee (preservation), followed by placement and connection rules. Every sentence earns its place with no 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 mutation tool with three parameters and nested card/connection objects, the description plus the rich input schema covers the essential invocation context. It could explicitly say to use create_canvas when the target does not exist, but 'existing' and the sibling context make this a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% and the description adds value beyond it, especially for connections: new cards can be referenced by index/title, existing cards by title. It also clarifies the append behavior and placement, which helps the agent understand the effects of the cards parameter.

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 ('Append') and resource ('existing v4 .klypix'), and clearly states the preservation behavior. This distinguishes it from sibling tools like create_canvas or read_canvas without relying on the title 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?

The description clearly frames this as the tool for modifying an existing canvas while preserving its content, which orients the agent toward 'add to existing' rather than 'create new'. It does not explicitly name alternatives like create_canvas or state exclusions, but the context is strong 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?

No annotations exist, so the description carries the full behavioral burden. It discloses lexical ranking, conditional semantic ranking only when a local model is installed, graceful degradation on fresh installs, inclusion of superseded/archived history with flags, attachment of live corrections, and the fact that it returns synthesis-ready context rather than writing prose. This is far beyond minimal 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?

The description is dense and fairly long, but every sentence adds meaningful information about behavior, usage, or outputs. It is front-loaded with the core purpose and supported by examples, ranking behavior, correction handling, and routing guidance. Slight trimming could improve readability, but the richness is justified for a complex tool.

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, absent annotations, and lack of an output schema, the description covers what an agent needs: question types, ranking behavior, historical context, correction awareness, return format (full cards + provenance + lifecycle), synthesis handoff, as_of semantics, and defaults. Nothing essential seems missing for correct selection and 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 coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema: it explains what as_of means behaviorally ('superseded cards count as live if they were current then'), gives concrete question examples for the question parameter, and clarifies the default canvas. This raises it above baseline, though k is only covered by its schema description.

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 verb and resource: 'Answer a natural-language question from the WHOLE project brain,' with concrete example questions. It distinguishes itself from search_canvases by stating that brain_ask is for questions, not keyword lookups. This leaves no ambiguity about the tool's role among its 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?

The description explicitly states when to prefer this tool: 'Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup).' It also names the alternative tool, explains the optional as_of parameter for historical questions, and notes the default canvas behavior. This is clear, actionable 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?

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 provided, the description carries the full burden and does so strongly. It discloses that the tool never archives or rewrites cards, that apply:true draws only additive and removable arrows, and that dry runs produce a before→projected receipt. This gives an agent a clear safety and side-effect profile beyond 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?

The description is dense but every sentence earns its place. It front-loads the default behavior, then explains the dry-run/apply effect, safety guarantees, scope alternative, and the reconciliation dismissal workflow. The structure is logical and efficient 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?

Given 7 parameters, no output schema, and no annotations, the description is remarkably complete. It covers the primary workflow, the apply behavior, the safety boundary, the special scope option, and the cross-tool integration with brain_reconcile. The only minor gap is the exact response structure beyond the mentioned receipt and count, but this is not critical 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 coverage is 100%, so the baseline is 3. The description adds meaningful beyond-schema semantics: the 0.55 vs 0.45 threshold distinction, scope behavior, and the specific use of pairs/relationship to dismiss a reconciliation false positive. This elevates it above baseline, though some params like canvas and max rely on schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: it repairs orphaned decision/milestone cards by proposing and drawing connections between related-unlinked brain cards. It also distinguishes itself by explaining the default scope, the whole-graph densification mode, and its relationship to brain_reconcile false positives. This makes its purpose unambiguous and separates it from sibling 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 usage context: default orphan repair, scope:"all" for whole-graph densification, and pairs with relationship:"not_contradiction" to dismiss reconcile false positives. It does not explicitly state when to avoid this tool in favor of sibling tools, but the provided use cases are clear enough for an agent to decide.

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, and it does so thoroughly. It explicitly states 'Never writes' and 'Read-only', clarifies that SESSIONS is never recent-chat history, and warns that a clean HARNESS reading does not mean other hosts have loaded the files. These caveats prevent real misinterpretation of the tool's 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 each sentence earns its place: it front-loads the read-only nature and output shape, then covers scope caveats and the CLI twin relationship. It could be slightly better organized with bullets, but it is not bloated and the important caveats are 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 diagnostic tool with two well-documented parameters and no output schema, the description provides the core verdict categories, the intended use case, and key limitations. It does not spell out exact verdict values or failure behavior such as network errors from `check_npm`, so it is strong but not fully exhaustive.

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 fully documents both `project` and `check_npm`. The description's references to 'optional npm currency' and 'projection drift' add mild context but do not materially extend what the input schema provides. Baseline 3 is appropriate because the description adds only peripheral color.

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-only self-check of the installed klypix brain' delivered as one verdict covering VERSION, CLAUDE, CODEX, TOOLS, SESSIONS, and HARNESS. It makes the tool's diagnostic role unmistakable and distinguishes it from sibling tools like brain_ask, brain_sync, or project_map_scan by focusing on installation health, synchronization, and liveness.

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 a clear trigger question: "Use to answer 'is my brain current, correctly installed, in sync, and who is actually live?' without file-spelunking." It also provides important scope guidance about HARNESS and which components get behavioral verdicts. It does not explicitly name sibling alternatives or say when not to use it, but the usage context is clear and not misleading.

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 and fully delivers: it discloses the non-invasive nature ('nothing is deleted'), deterministic selection thresholds, protected areas, the hard approval gate ('apply is REFUSED without it'), exact effects on the originals, and the one-undo un-gardening guarantee. It also warns that the agent is never shown the code, preventing fabricated approvals.

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 every clause carries load-bearing operational information; the core safety promise is front-loaded and the workflow, criteria, effects, and trigger are all tightly packed. There is no filler or repetition of the schema without added context.

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 two-phase, approval-gated mutation tool with no annotations and no output schema, the description is remarkably complete: it covers when to run, what the dry run returns, how to get approval, what apply does, what happens to the originals, and how to undo. An agent has enough to safely execute both phases.

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?

Although schema coverage is 100%, the description adds significant phase-dependent meaning: apply=false returns areas plus card text, apply=true consumes syntheses and requires the approve code. It also ties syntheses to exact dry-run area titles and emphasizes the human-generated 8-char code, going beyond the schema's structural 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 opens with a specific outcome ('Tidy an over-grown brain... consolidate') and immediately states the mechanism: it consolidates only DORMANT cards and never load-bearing ones. It clearly describes the two-phase flow and the resulting synthesis card, which distinguishes it from siblings like brain_insights, brain_connect, and brain_reconcile.

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,' and it lays out the exact two-phase dry-run-then-apply protocol. It does not explicitly name sibling alternatives or when-not-to-use cases, so it misses the top bar for exclusions.

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 and does well: it states the tool is read-only and never writes, explains that timeline events are only included for the timeline view, and describes the structured payload size and the structured default behavior. Minor gaps remain around error behavior, but the key safety and return-shape traits are 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 description is long but densely informative, covering the main purpose, each view, key defaults, and usage. It is front-loaded with the core concept and every major clause contributes. Slight redundancy like 'Read-only by construction — it never writes' could be tightened, but it does not bloat the text.

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 there is no output schema and no annotations, the description gives enough detail for an agent to call the tool correctly: it explains what each view returns, how root and structured behave, and what question types the tool answers. The markdown vs. structured output distinction is also addressed.

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 valuable meaning beyond the schema for root (card title prefix or id, defaults to most-connected hub), view (events omitted unless timeline), and structured (large payload, default false, historical behavior). This exceeds 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?

The description clearly states the tool returns one structured payload of brain lens views and enumerates what each view contains (freshness, provenance, activity, timeline, orrery, unresolved). It distinguishes itself as the read-only data twin of the desktop Brain Lenses, making its role distinct from sibling tools like brain_ask 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?

It gives explicit use cases: "what's rotting / who wrote this / what happened this week / what's around X / what's undecided" or feeding a UI. It does not explicitly name alternatives or state when not to use this tool, but the described intents provide clear 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?

With no annotations provided, the description carries the full burden, and it delivers extensively: delivery is OS-user-local, machine-local, bounded by a 24h TTL, ephemeral, and replayable after reconnect. It also clarifies acknowledgment semantics (not proof of human reading), auto-consumption behavior, and failure receipts, which is far beyond typical 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?

The description is long but densely packed with non-redundant behavioral details that matter for correct use. The front-loaded purpose sentence and examples make the primary intent immediately clear; the later lifecycle details are verbose but justified by the unusual ephemeral delivery semantics.

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 covers nearly everything an agent needs: recipient targeting, ephemerality, delivery constraints, expiration, receipt semantics, and the distinction from brain_note. The only minor gap is that it never explicitly describes the response/return shape, though it references a 'receipt line'.

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 all three parameters clearly. The description adds examples of message content and behavioral context, but it does not add new parameter-level meaning beyond what the schema provides. The 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 names a specific verb ('Leave'), a specific resource ('note for the OTHER active agent sessions'), and the intended scope ('working on this project right now'). It also differentiates itself from the durable brain_note tool by explicitly stating this is ephemeral and not persisted, which is the key distinction among sibling 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?

It gives clear when-to-use guidance: leave a deliberate, targeted note for other live sessions. It explicitly contrasts with brain_note ('for a durable decision use brain_note instead'), and it describes the delivery conditions, such as requiring the peer to take a supported action. This is sufficient routing guidance for an agent.

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

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

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?

The description discloses lifecycle behavior beyond what annotations provide (which is none, since no annotations are supplied): new decisions supersede overlapping older ones, ✓ resolves/archives a matching card, ~ updates in place, and skills 'resurface every session and never age out.' It also exposes the potential side effect of SUPERSEDING/dedup and the guard card's PreToolUse behavior for blocking/warning. It does not fully inventory every side effect (e.g., evidence fingerprinting) but for an 8-parameter tool with no annotations, this is still strong 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?

The description is dense but every sentence earns its place: it defines the tool's niche, differentiates from a sibling, lists the marker meanings, explains guard cards, and notes the default canvas. It is a long paragraph rather than a scannable list, but for a complex 8-parameter tool covering multiple card types, the length is mostly 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?

For a tool with nested objects, 8 parameters, multiple marker modes, guard behavior, and no annotations or output schema, the description covers the necessary context: what the card lifecycle does, when to use guard/block, how markers change behavior, what the default canvas is, and how this relates to siblings. Even though the schema already covers each parameter, the description supplies the cross-cutting semantics that make the tool safely usable.

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?

With 100% schema description coverage, the schema already documents every parameter. The description adds meaning by mapping markers to lifecycle behavior (+, ✓, ~, etc.), clarifying the difference between a skill and a decision, and adding the nuance that guard-card severity 'block' should never be authored without explicit user instruction. It doesn't add exact formatting for every field beyond the schema, but it goes beyond merely repeating 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 description names a highly specific verb+resource ('Record something in the project brain ON DEMAND') and covers every marker type and lifecycle behavior (decision, question, milestone, skill, resolve, update, guard). It explicitly distinguishes itself from add_to_canvas, so an agent can tell them apart without opening schemas.

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 a clear when-to-use ('record a decision, ask an open question, mark a milestone, log a skill, resolve a finished item, or correct a card'), explains what the tool does not do (not a flat append like add_to_canvas), gives concrete examples ('always dedup zKeys before REORDER'), and clarifies defaults ('Defaults to the project brain ("brain")'). It also explains guard-card usage and the block severity constraint, which is strong context that would otherwise be missing.

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 clearly states safety: 'Reads ONLY the filesystem — never the database, never the network — and changes nothing.' It discloses persistence semantics for false-positive dismissals, marks candidates as 'candidates only, YOU confirm each', and notes that claims/plans are 'never auto-archived'. This is unusually transparent.

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 is genuinely complex and the text is scannable with bolded section labels. It front-loads the core purpose and each sentence carries behavior or usage content. A little trimming would be possible, but the density and structure earn a high 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 tool with no output schema, no annotations, and three optional parameters, the description covers the modes, expected findings, interpretation cues, safety profile, and follow-up workflows. It tells the agent what the tool will surface, what requires user confirmation, and how to persist dismissals. Combined with the detailed schema enum descriptions, nothing essential is missing 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 main description reinforces what mode means but adds no parameter-level detail beyond the input schema's own descriptions of mode, root, and canvas. It does not introduce new syntax, defaults, or relationships between parameters, so it neither compensates nor falls short.

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 'Truth maintenance' and then names precise actions: 'finds same-subject live card pairs', 'lists committed migration files', and 'pre-v1.15 raw-bash ship cards to tidy'. It clearly identifies the resources being reconciled and separates this from siblings like read_canvas or brain_challenge. The title's 'reconcile' jargon is fully resolved by the body.

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 periodically, or when recall surfaces something you believe is stale.' It also routes follow-up actions to siblings, telling the agent to retire stale cards via brain_note and dismiss false positives via brain_connect with relationship 'not_contradiction'. It does not list explicit when-not-to-use alternatives, so it stops short of 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?

The annotations cover idempotency and non-destructiveness, and the description adds substantial behavioral context: fail-closed completion, exact-path conflict matching, machine-local/OS-user-local coordination, release lease and claim semantics, and late-arrival alerts. No contradiction with the annotations is present.

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 not redundant; the critical 'Call FIRST' instruction is front-loaded. Every sentence contributes a distinct operational fact: call phases, response contents, fail-closed behavior, portability, and important limitations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately summarizes what a response contains: task context, active task peers, one-time messages, exact-file conflicts, and late-arrival alerts. Limits and failure behavior are also covered, while the complex nested parameters are fully documented in the input 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 detailed property docs already carry the parameter-meaning burden. The main description adds minor context like 'concise intent and expected files' and 'machine-checkable result manifests', but it does not systematically add 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?

States a specific verb and resource: an approval-free task gateway that synchronizes task scope, peers, conflicts, and relevant memory. The phase protocol (start/checkpoint/complete) and the returned payload are explicit, clearly distinguishing brain_sync from siblings like brain_ask, brain_reconcile, or brain_message.

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 prescribes when to call: first with intent and files, again when scope changes, and with phase 'complete' before the final response. It also explains scope replacement/merging and host-agnostic suitability. It does not name explicit alternatives or when-not-to-use cases, so it stops short of a full 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 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?

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 provided, the description carries the full burden, and it does so well. It discloses that image assets are attached up to a specific cap (first 8 images under ~5MB each), with larger canvases falling back to filenames, and that multiple input forms are accepted. This gives the agent a realistic expectation of the tool's behavior and limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense but well-organized: it front-loads what the tool does, then details the image cap, then gives the input guidance. Every clause contributes useful information without 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 single-parameter read tool with no output schema, the description fully explains both the return content (structured markdown with cards, graph, wikilinks, tags) and the image-asset behavior. Nothing essential is missing for an agent to invoke and interpret the result 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 schema already covers the single parameter at 100%, describing title/filename/path options. The description adds meaningful nuance by saying the canvas TITLE can be passed directly and that listing/searching is unnecessary, which clarifies the intended calling pattern beyond the schema's raw parameter description.

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 ('Read'), a specific resource ('a KLYPIX canvas'), and precisely what the output contains (structured markdown with cards, connection graph, wikilinks, and tags). It also differentiates itself from sibling search/list tools by stating the caller does not need to list or search first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: pass the canvas title directly, and there's no need to list or search first. It does not explicitly name sibling alternatives for cases like finding a canvas by content, but the direct-input guidance 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?

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?

With no annotations, the description carries the full burden of behavioral disclosure. It does state the scope ('every canvas in the vault') and the return behavior ('Returns the canvases and the matching cards'), which is useful. However, it does not disclose details like case sensitivity, exact tag syntax, whether archived or hidden canvases are included, or that the operation is purely read-only.

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 just two sentences with no filler. It front-loads the action and scope immediately, then gives the return value in the second sentence. Every word 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?

For a single-parameter search tool with no output schema, the description provides the essential information: what content is searched, the scope, and what is returned. It is complete enough to invoke correctly, though it could be improved by naming sibling alternatives explicitly or describing output structure in more detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents the only parameter, 'query', at 100% coverage, so the baseline is 3. The description adds some context by tying the query to card text, titles, and #tags, but it does not add examples, syntax details, or edge-case behavior 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 uses a specific verb ('Search') and a specific resource ('card text, titles, and #tags across every canvas in the vault'), and it states the return value. This makes it clearly distinguishable from sibling tools like list_canvases, read_canvas, and even search_all_brains, since it scopes to canvas content vault-wide.

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 intended use is implied: use this tool to find text or tags inside any canvas in the vault. However, the description does not explicitly say when to prefer this over search_all_brains or other sibling search tools, nor does it mention any exclusions or alternatives.

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