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 discloses that supersedes closes the target out (kept in history, hidden from search, never deleted), that re-asserting between the same pair replaces the prior assertion, and that automatic contradiction detection is deliberately absent. It stops short of permissions/auth or concurrency details, but the side-effect profile is unusually well covered.

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 long, but the length is justified by eight relation types that each require distinct semantics, and the purpose is front-loaded in the first sentence. Minor verbosity in the repeated 'normally set automatically by ...' phrasing, but nothing 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 domain-complex, annotation-free mutation tool with an output schema, the description supplies the relation taxonomy, directionality, manual-vs-automatic guidance, and side effects. Return values are covered by the output schema, so nothing essential 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 0%, so the description must compensate, and it does: the Args block defines all four parameters and gives a full semantic breakdown of every relation enum value beyond the bare string list. An agent knows exactly what source_id and target_id mean relative to the chosen relation.

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 (assert) and resource (a typed, directional relationship between two captures), and immediately clarifies the directionality (source → target). This clearly distinguishes it from siblings like assert_entity, find_connections, or rebuild_connections.

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 spells out exactly when each relation applies, and crucially notes which relations (distills, assesses, observes) are normally set automatically by commit_distillation/commit_assessment/commit_observation and that manual assertion is for fixing or adding missing links. It also explicitly rules out automatic contradiction detection, telling the agent that a human must assert supersession.

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 usefully discloses that entities are global across volumes and auto-created by '@' tags, but says nothing about idempotency, what happens if the entity already exists or is already linked, or error behavior for an unknown capture_id.

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 core action in the first sentence, then adds useful context, then lists args. It is well-sized with little waste; the parenthetical kind examples are the only slightly padded element.

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 an output schema exists, return values need not be described. The description covers purpose, usage context, global-scope semantics, and all parameters, leaving only mutation edge cases undocumented.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains capture_id, name ('display form as written'), and expands kind into an enumeration (person|place|work|org|symbol|other) that the schema itself lacks.

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 ('link') and resource ('named entity ... to a capture') with concrete examples of entity kinds. It differentiates itself from the sibling assert_connection by scope (entity-to-capture rather than connection graphs).

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

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

It clearly scopes usage — 'covers what extraction missed or mis-typed' — and explains that '@' tags auto-create entities, implying this tool is the manual fallback. There is no explicit statement of when NOT to use it or a named alternative, so it falls 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 provided, the description carries the full burden and delivers: it discloses that the tool does NOT write to the database, instead preparing instructions for Claude, that it declines without a REV page, and that it never mutates the claimed status. These are exactly the behavioral traits an agent needs and cannot infer from 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 purpose, then sequencing, then args, then returns — a clean structure. It is somewhat long and the surface_connections analogy is illustrative rather than load-bearing, but almost every sentence carries usable information.

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

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

For a tool with an output schema (so return values needn't be re-explained, though they are summarized), the description covers preconditions, decline behavior, audit scope, and persistence handoff. Nothing an agent needs to invoke 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 coverage is 0% (no descriptions, no enums), so the description must compensate fully. It does: rev_template_id is documented with format ('REV-008') and requirement semantics ('declines if no REV page with this ID exists'), and depth is spelled out with its enum values, default ('standard'), and the 'more on this one' override.

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: 'Independently check a Review page's claimed Knowledge Status against evidence in the journal.' It even defines the scope of what gets audited (Solid/Mastered, not Needs Work), so an agent can distinguish it from siblings like commit_assessment or knowledge_progress.

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 sequencing ('runs AFTER a REV page exists — never before'), a stated failure mode ('If no REV page is found, the tool declines'), an inclusion/exclusion rule ('Only Solid and Mastered claims get audited'), and the follow-up path ('Call commit_assessment() after the user reviews the outcome'). This is textbook when/when-not/alternatives 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 does so richly: it discloses that it does NOT write to the database, that it reuses dream_correlation()'s co-occurrence data with the same guardrails (window_days, match count, base rate, never 'correlation'), that it never rewrites the DC narrative, and that its output is a 'noticing' not a conclusion or an asserted symbol meaning.

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 purpose and precondition, and nearly every clause carries distinct information. It is long and heavily parenthetical, which adds density and some friction, but the content is not redundant or padded.

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 an output schema present, the description supplies everything an agent needs: preconditions, guardrails, side-effect profile, persistence follow-up, and a brief return summary. No material gap remains 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 0%, so the description must compensate, and it does for all three params: dc_template_id with an example ('DC-005') and its required/decline behavior, window_days defined as 'how many days apart counts as near' with default 3, and depth enumerated as brief/standard/deep with a default and a 'more on this one' override.

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 a Dream Capture entry for cross-domain echo') plus the concrete scope (RC/REV entries sharing a theme within a few days) and names the actual product of the tool ('prepare a dialogue'). It implicitly distinguishes itself from dream_correlation by noting it reuses that tool's data rather than duplicating it.

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

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

Gives an explicit precondition ('runs AFTER a DC page exists — never before'), an explicit failure mode ('if no DC page is found, the tool declines'), explicit follow-up routing ('call commit_observation() after the user reviews the outcome'), and even trigger phrases. When-to-use and when-not are both spelled out.

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

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

No annotations are provided, so the description carries the full burden and does so: accept-by-default (no page skipped), pages with unreadable template IDs or taken IDs become Wild Art entries with a recorded reason, the default OCR backend is local Tesseract with poor cursive performance, and cloud OCR is off by default and announced per run. Mutation semantics of force (replace vs. leave existing untouched) are spelled out.

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

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

Front-loaded with the core action, then the pipeline behavior, the OCR caveat, and an Args block — a sensible order. The only waste is the force/id_conflict behavior being stated in both the body paragraph and the Args section.

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 batch mutation tool with no annotations, the description covers side effects, fallback behavior, failure recording, OCR defaults, and follow-up remediation via list_by_tag and promote_capture. An output schema exists, so return values need no further explanation beyond the summary-table mention.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: folder_path is documented as an absolute path, force is given detailed replace-vs-id_conflict semantics, and volume is tied to the 'second or later journal' case. Volume's default of 0 and exact effect are never explained, leaving one small gap.

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 + resource + scope: it finds every image in a folder and runs the full upload pipeline on each. It is clearly distinguishable from single-page siblings like upload_capture and manual_capture, and it names the image formats it handles.

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?

Routes the agent explicitly: for a handful of pages use manual_capture instead, and for large handwritten imports enable cloud OCR (with the env var and README pointer). It also states when volume=N should be passed. Both the alternative and the condition that selects it are given.

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

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

With no annotations, the description carries the full behavioral burden and does disclose real traits: sequential ID assignment at write time, one entry per confirmed insight, and a tagging side effect ('All entries are tagged as AI-Extracted'). It omits permissions, validation/error behavior, and whether re-running duplicates entries, leaving some gaps for a mutation tool.

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

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

Purpose is front-loaded in the first sentence, followed by storage behavior, usage condition, and an Args block. It uses more vertical space than needed due to the docstring-style formatting, but every section earns its place without redundant prose.

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 no annotations, the definition covers purpose, upstream dependency, storage semantics, the full parameter structure, and the return shape. An output schema exists so the description needn't detail return values, and it still notes the confirmation. Remaining gaps (permissions, idempotency) are minor.

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

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

Schema description coverage is 0%, so the description must compensate, and it does substantially: it enumerates the top-level JSON fields (entry_type, date, source_platform, session_focus, insights, open_questions, action_items) and the nested insight fields (text, confidence_tier, tags, connections). It stops short of formats or allowed values for fields like entry_type and confidence_tier.

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: 'Write confirmed AIEX insights to the knowledge base', and adds that each insight becomes a separate AIEX-NNN entry. It is clear and concrete, but it does not distinguish itself from the other commit_* siblings (commit_distillation, commit_assessment, commit_observation), so an agent must infer the difference from the AIEX naming.

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 prerequisite and upstream tool: 'Call this after the user has reviewed and approved the output from extract_insights().' This tells the agent when to invoke it relative to a named sibling, but offers no when-not guidance or contrast with the other commit 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, the description carries the full burden and does so well: it discloses that it never changes the REV page's claimed status, stores with source='ai_extract' (excluded from journal_health KPIs), uses the AIEX sequence, and links via an asserted 'assesses' edge. It also notes the return shape.

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

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

Front-loaded with the core action and the behavioral constraints next, then the argument documentation. Every sentence earns its place, though the description is on the long side for a single-parameter 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?

An output schema exists, so return-value explanation is not required, and the description nonetheless summarizes the confirmation. Combined with the rich behavioral and parameter detail, an agent has everything needed to invoke this 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 0%, so the description must compensate, and it does: it fully documents the assessment_json fields including which are required (rev_template_id, assessment), the semantics of each optional field (reaffirmed, revised, tags, date), and defaults. This adds substantial meaning beyond the bare 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: storing the confirmed outcome of an audit_knowledge_status() dialogue. It distinguishes itself from siblings by referencing audit_knowledge_status (the upstream) and commit_distillation (a contrasting sibling that never rewrites a SYN page).

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 states the trigger condition: call after the dialogue concludes and the user has reviewed the assessment. It names the related upstream tool, giving strong context. It does not state explicit when-not-to-use conditions, so it falls just 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 so richly: it discloses that no SYN template ID is created, that the entry is stored with source='ai_extract' (excluded from journal_health KPIs, discoverable in get_breakthroughs()/export_html()), that it uses the AIEX sequence, and that it asserts a 'distills' edge to the SYN page. This is exactly the behavioral context an agent needs before writing.

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 and the Args block is well-organized and necessary given the nested JSON payload. It is slightly long and includes a few soft phrases ('This is the artifact'), but nearly every sentence conveys operationally relevant detail rather than 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 complex write tool with a structured payload, the description covers the source flag, ID sequencing, edge assertion, and return confirmation (AIEX ID and distills edge). With an output schema present, return values need no further unpacking, so nothing an agent needs 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 coverage is 0% (the lone param is an opaque string), so the description must compensate and it fully does, enumerating every JSON field: syn_template_id (required), distillation (required, with sentence guidance), the five optional connection-map lists, tags, and date. This adds far more meaning than the schema 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?

States a specific verb and resource ('Store the confirmed outcome of a surface_connections() dialogue') and immediately clarifies scope by excluding what is NOT stored (the connection list, the transcript). An agent can distinguish this from commit_assessment, commit_observation, and commit_aiex from the first two sentences.

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 trigger condition: call after the Phase 2 dialogue concludes and the user has reviewed the revised connection map. That ties it clearly to its predecessor surface_connections(). It stops short of naming alternative commit_* siblings or when NOT to use it, keeping it at a strong 4 rather than 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 load and does well: it discloses the mutation boundary (never changes the bridged DC page's dream narrative), the storage semantics (source='ai_extract', excluded from journal_health KPIs), the AIEX sequence, and the 'observes' edge creation. It omits risks like duplicate handling or whether prior observations are overwritten.

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 verb+resource immediately, but the middle paragraph defending 'observation' vs 'inference' is philosophically padded and could be trimmed. The remainder (behavior, args) is dense and useful.

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 zero annotations and an opaque single-param schema, the description supplies everything an agent needs: when to call, what gets written and where, identifiers, edge semantics, and a return summary. An output schema exists but the description's return note is supplementary, not redundant.

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

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

Schema coverage is 0% and the single parameter is an opaque JSON string, yet the description fully compensates by enumerating every field, marking required vs optional, specifying types (lists of strings), defaults, and the 2-5 sentence constraint on the core 'observation' field.

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: 'Store the confirmed outcome of a bridge_dream_research() dialogue.' It explicitly distinguishes this from what it is not ('observation,' not 'inference') and differentiates from siblings like commit_distillation, so an agent can route precisely.

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 clear timing ('Call this after the dialogue concludes and the user has reviewed the observation') and scope exclusions ('Only the observation — not a restatement of the dream or an asserted symbol meaning'). It also names the related tool bridge_dream_research() whose output it consumes.

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 delivers: it discloses that original OCR text is preserved (non-destructive), that corrected text becomes the new source for search/tag/connection logic, and that it re-runs parsing, tag extraction, and connection detection. This is rich behavioral context beyond a simple 'update'.

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 purpose, then when-to-use, then side effects, then parameter notes. Sentences are tight and each earns its place. Slightly long but justified by the parameter explanations and behavioral details. Could be marginally tighter but no waste.

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 an output schema present, return values needn't be detailed further. The description covers non-destructive behavior, downstream effects, re-processing, and both parameters thoroughly. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: 'capture_id' is explained as the numeric capture ID (shown as #N in upload output and search results) and explicitly distinguished from the template ID; 'text' is described as the full corrected transcription including field labels and all schema tags. This adds meaning beyond the bare schema types.

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 ('correct') and resource ('OCR transcription'), and immediately clarifies the scope: replacing stored transcription with corrected text. The verb is precise and distinguishable from siblings like rebuild_connections (which rebuilds rather than corrects). No ambiguity about what the tool 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?

Provides a concrete when-to-use scenario: 'when a capture's OCR came out wrong — for example a Tesseract read of handwriting, or a transcription typo.' This gives clear context. However, it doesn't explicitly state when NOT to use this tool or name alternatives (e.g., manual_capture vs. correction). Still, the scenario is specific enough for confident 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, the description carries the full behavioral burden and does well: it discloses that output is purely descriptive, that every result includes window_days, match count, and per-population base rates, and it explains the researcher-degrees-of-freedom rationale for not labeling results as 'correlation'. This goes well beyond a bare read/analysis disclosure. It does not state computational complexity, refresh behavior, or permission requirements, which keeps it short of a 5.

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

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

Core purpose is front-loaded in the first sentence, which is good, but the parenthetical about researcher degrees of freedom is lengthy and partly editorializing rather than specification. It earns some place by justifying the descriptive-only stance, yet a tighter phrasing could convey the same behavioral guarantee. Args block is well structured.

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 two parameters, no annotations, a presence of output schema (so return values needn't be explained), and the analytic nature of the tool, the description is largely complete. It covers what is computed, how matching works, the symmetric window, and what each result reports. It omits any mention of performance implications for large journals or how ties/duplicates are handled, keeping it just short of 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 0%, so the description must compensate, and it largely does: it explains that tag is a # topic/theme value matched across DC's #theme and RC/REV's #topic tags (same prefix, normalized value, different template role) and that window_days is a symmetric day-distance threshold with default 3. This adds real semantic meaning absent from the schema. Minor gaps remain: no format examples beyond one, no bounds on window_days.

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 (report co-occurrence), the two concrete resources it spans (Dream Capture entries and RC/REV entries), and the exact matching dimension (#tag within window_days). It is clearly distinguishable from siblings like dream_patterns or bridge_dream_research, which do different analyses. An agent can tell exactly what this tool computes without inspecting the schema.

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

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

Usage is implied (analyze tag co-occurrence between dreams and research entries), but there is no explicit statement of when to choose this over dream_patterns or bridge_dream_research, nor any exclusion criteria. The 'descriptive only' caveat hints at a usage boundary but does not name an alternative. An agent gets a reasonable sense of context but must infer relative routing.

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 discloses that the tool aggregates data across all entries and that output quality depends on input volume, which are useful behavioral traits. However, it doesn't mention performance characteristics, error conditions, or specific output format details, leaving some gaps in transparency.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by elaboration in two concise sentences. Every sentence adds value by explaining scope, aggregation details, and data dependency, with zero wasted words or repetition.

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

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

Given the tool has 0 parameters, no annotations, and an output schema exists, the description provides sufficient context for understanding its purpose and usage. It covers what the tool does and how input volume affects results, though it could briefly hint at output structure to fully leverage the 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on the tool's function without redundant parameter info, earning a high baseline score for not introducing unnecessary complexity.

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's purpose with specific verbs ('Analyze recurring patterns', 'Aggregates symbols, emotions, and themes') and resources ('all Dream Capture entries', 'DC pages'). It distinguishes itself from siblings by focusing on pattern analysis rather than upload, export, search, or other operations.

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 usage context by stating 'The more DC pages you upload, the more meaningful the patterns become,' suggesting it's best used with substantial data. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_stats' or 'find_connections,' nor does it provide exclusions or prerequisites.

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. It discloses what is written (all captures fields, tags, entities, connections), the format (versioned JSONL, ksj-export-v1), and the existence of a documented format and an import path, but it doesn't mention overwrite behavior, error handling, or whether writing is atomic.

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 well-organized sentences plus an Args block. Front-loaded with the core action and format. It's slightly longer than strictly necessary due to the docs pointer, but every sentence adds useful 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 single-parameter export tool with an output schema, the description covers the use case, scope, format, import coupling, and parameter default. The output schema handles return value details, so the only remaining gap is operational nuance like overwrite behavior.

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 undocumented in the schema (0% coverage). The description compensates by explaining file_path's purpose and default, which is exactly what an agent needs to invoke correctly.

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 ('Write the entire knowledge base to a versioned JSONL file'), names the format (ksj-export-v1), and distinguishes itself from siblings like export_captures and export_html by emphasizing it's a full backup with an import path.

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 says it's 'a real backup with a matching import path, not a one-way dump,' contrasting it with export_html and export_captures but without explicitly naming those siblings or detailing when a user should choose export_backup over them.

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 well by disclosing key behaviors: it exports data without writing a file (clarifying output as a string), supports filtering by tag, and specifies default values. However, it misses details like rate limits, authentication needs, or error handling, which would enhance transparency.

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 appropriately sized and front-loaded, starting with the core purpose, followed by parameter explanations and return details in a structured format. Every sentence adds value without redundancy, making it efficient and easy to understand.

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 moderate complexity, no annotations, and the presence of an output schema (which handles return values), the description is complete enough. It covers purpose, parameters, and behavioral aspects like no file writing, leaving no critical gaps for agent understanding.

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 description adds significant meaning beyond the input schema, which has 0% description coverage. It explains the purpose of 'format' (Markdown or JSON with default) and 'tag_filter' (optional filtering with an example), compensating fully for the schema's lack of details and providing clear parameter semantics.

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

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

The description clearly states the specific action ('Export all captures or a tag-filtered subset') and the output formats ('as Markdown or JSON'), distinguishing it from siblings like 'search_captures' or 'list_by_tag' which likely have different functions. It precisely defines what the tool does without being vague or tautological.

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 provides clear context for usage by mentioning the tag-filtering option and default format, but it does not explicitly state when to use this tool versus alternatives like 'export_study_deck' or 'search_captures'. It implies usage for exporting data but lacks explicit comparisons or 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?

No annotations are provided, so the description carries the full burden. It over-delivers on output behavior (tabs, navigation, footer versions, inlined data / snapshot semantics) which is genuinely useful, but it says nothing about permissions needed, whether the file is overwritten, or side effects on existing files. For a write-to-disk tool, that mutation/permission context is missing.

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 bulk of the description is a UI feature tour (tabs, controls, graph layout, history behavior) rather than information an agent needs to invoke the tool. It is heavily back-loaded: the only actionable invocation guidance (file_path) sits at the very end. For an agent-selection definition this is bloated and mis-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?

With an output schema present, return-value explanation isn't needed, so the heavy UI description is largely redundant for invocation. The description covers the write target and snapshot semantics adequately, but omits the deployment-adjacent essentials: overwrite behavior, error conditions, and why this tool versus the other export siblings.

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

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

Schema description coverage is 0%, so the description must compensate. It does: the Args section explains file_path is where to write, that the default (empty) writes ksj-view.html into the KSJ data directory, and that empty is recommended and required on Windows. That is meaningful semantics beyond the bare string type, though it doesn't cover format/overwrite behavior.

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 verb and artifact: write a self-contained HTML bird's-eye browser of the whole knowledge base. It distinguishes itself from sibling exports (export_backup, export_captures, export_study_deck) by describing an interactive offline viewer. However, it never explicitly names those siblings or states contrast, so it's clear on purpose but not sharply differentiated.

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

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

Usage context is implied — you'd call this to get a shareable, offline-viewable snapshot — but the description never says when to prefer this over export_backup, export_captures, or export_study_deck. There is no when-not-to-use guidance or alternative routing, so it falls to the minimum-viable tier.

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. It discloses key behavioral traits: it transforms questions into flashcards with specific formatting (front, back, tags), outputs as tab-separated CSV, and explicitly states 'No file is written to disk.' This covers output format and side effects, though it doesn't mention rate limits or authentication 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 description is well-structured and appropriately sized. It front-loads the core purpose, then details the transformation process, output compatibility, and parameter usage. Every sentence adds value with no redundancy, making it efficient and easy to parse.

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 moderate complexity, no annotations, and an output schema present, the description is complete. It explains what the tool does, how it processes data, output format, parameter usage, and behavioral constraints. With an output schema handling return values, no additional explanation of outputs is needed.

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 has 0% description coverage, so the description must compensate. It adds detailed meaning for the single parameter 'tag_filter': explains it's optional, provides an example ('machine-learning'), and clarifies that leaving it blank exports all questions. This fully documents the parameter beyond the bare 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 clearly states the tool's purpose: 'Export your open questions as a portable study deck (tab-separated CSV).' It specifies the verb 'export' and the resource 'open questions,' and distinguishes it from siblings like 'export_captures' by focusing on study decks with flashcards from journal questions.

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 provides clear context for when to use this tool: for exporting open questions as study decks, compatible with tools like Anki and Quizlet. It doesn't explicitly mention when not to use it or name alternatives, but the focus on flashcards from journal questions implies it's for study purposes rather than general data export.

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. It clearly states 'This tool does NOT write to the database' and explains the two-step workflow. It also describes what it loads (knowledge base context, existing tags) and what it returns (context block + extraction instructions). However, it doesn't explicitly state whether this is a read-only or side-effect operation in annotation terms, though the text implies read-only preparation.

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

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

The description is well-structured with a clear purpose statement, a workflow explanation, a negative constraint, and trigger phrases. It is slightly verbose with some redundancy (e.g., repeating the extraction flow), but every section serves a purpose and is front-loaded with the core action.

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 (two-phase workflow, no annotations, 0% schema coverage), the description is largely complete: it explains purpose, parameters, behavioral constraints, and the follow-up tool. However, it doesn't describe the output schema details (though output schema exists, so that's acceptable) and could clarify error conditions or rate limits. It is sufficient 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 0%, so the description must compensate. It documents both parameters: session_text ('Full or partial transcript of the research session') and source_platform ('Platform where session occurred... Leave blank if unknown'). This adds meaningful guidance beyond the bare schema, though it doesn't specify format constraints or examples for session_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 states a specific verb and resource ('Prepare an AI research session for insight extraction') and clarifies the two-phase flow: load context, return instructions, then Claude performs extraction. It explicitly names the sibling tool commit_aiex() as the follow-up step, distinguishing this preparation step from the commit step.

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 provides explicit trigger phrases ('Extract insights from this session', 'Run AIEX on this conversation'), states when to use commit_aiex() (after user reviews extracted insights), and clarifies that this tool does NOT write to the database. This is comprehensive when-to-use and 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, and it discloses meaningful behavior: references are listed first and always shown, tag overlap is ranked by IDF-weighted strength, and "the total is always reported" even when limit truncates. It lacks any note on permissions or cost, but for a read-only discovery tool the behavioral picture is solid.

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 core behavior is front-loaded in the first sentence, followed by a clean Args block. Every sentence earns its place – no filler and no redundancy with the structured fields.

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

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

An output schema exists, so return values needn't be spelled out, and the ordering/IDF semantics are covered. The remaining gap is the absence of any tie-in to sibling tools, which matters given eleven-plus closely related connection and capture tools.

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

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

Schema description coverage is 0%, so the description must compensate fully, and it does: capture_id is tied to its origin (upload_capture/search_captures), min_strength is given a concrete calibration ("2.0 ≈ two ordinary shared tags or one rare one"), and limit's interaction with the always-reported total is explained.

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 ("Show connections for a capture") and details two distinct edge types: @-references (both directions) and IDF-weighted tag overlap. This is far more specific than a restatement of the name. It does not explicitly differentiate from siblings like surface_connections or neighborhood, so it falls short of a 5.

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

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

Usage is implied through the argument explanations – e.g. "Lower it to see weaker links" tells the agent when to tune min_strength. However, it never names an alternative tool (surface_connections, neighborhood, find_path) or the condition that would select this tool over them, which a crowded sibling set makes valuable.

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 does add real behavioral context by enumerating how two captures can be linked (references, shared entities, asserted relations, tag overlap), which is more than the schema conveys. However, it says nothing about read-only nature, cost/latency of a graph search, what happens when no path exists, or path optimality guarantees.

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 core purpose is front-loaded in the first sentence with the edge-type detail immediately after, and the Args block is minimal. The args section largely restates the schema, but the 'numeric ID' clarification 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?

An output schema exists, so return-value explanation is not required. The description is adequate for a two-parameter read tool, but gaps remain: no sibling differentiation for a crowded graph-query namespace, no no-path/error behavior, and no indication of search direction or scope.

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

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

Schema description coverage is 0%, so the description must compensate, and it does document both parameters with meaning: from_id as the starting capture and to_id as the destination, both numeric IDs. Type and directionality are clear, though no constraints (e.g., valid ID range, self-path handling) are given.

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

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

The description gives a specific verb and resource ('find the shortest chain of connections between two captures') and even names the edge types traversed (references, shared entities, asserted relations, tag overlap). It does not, however, distinguish itself from close siblings like find_connections, surface_connections, or neighborhood, which an agent could easily confuse it with.

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?

There is no explicit when-to-use guidance, no conditions under which this is preferred over alternatives, and no mention of the many graph-related siblings (find_connections, surface_connections, neighborhood). The agent must infer usage purely from the purpose sentence.

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 describes the tool as a read operation ('Return all Synthesis entries') and specifies the output format and ordering, which is helpful. However, it lacks details on potential limitations like pagination, rate limits, or error conditions, which are important for a tool that might return large datasets.

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 appropriately sized and front-loaded, with the first sentence stating the core functionality clearly. Each subsequent sentence adds meaningful context without redundancy, such as detailing the returned fields and the tool's purpose for tracking thinking evolution. There is no wasted text, making it efficient and well-structured.

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 (0 parameters, no annotations, but with an output schema), the description is mostly complete. It explains what the tool does, the data returned, and its use case. Since an output schema exists, it need not detail return values, but it could benefit from mentioning behavioral aspects like performance or data scope. Overall, it covers the essentials well.

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 has 0 parameters with 100% coverage, so the schema fully documents the absence of inputs. The description adds value by explaining that no parameters are needed and implicitly clarifies the scope ('all Synthesis entries'), which compensates for the lack of parameters. It does not need to detail parameters, so a baseline of 4 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 clearly states the tool's purpose with specific verbs ('Return all Synthesis entries') and resources ('Synthesis entries'), distinguishing it from siblings like 'search_captures' or 'find_connections' by focusing exclusively on SYN entries. It explicitly mentions what data is returned ('breakthrough field, patterns identified, $ insight tags, and topic tags') and the chronological ordering, making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool ('to see how your thinking has evolved and which ideas led to the biggest discoveries'), implying it's for retrospective analysis of breakthroughs. However, it does not explicitly state when not to use it or name alternatives among sibling tools, such as 'search_captures' for filtered results, leaving some guidance gaps.

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 full burden for behavioral disclosure. While 'Return an overview' implies a read-only operation, it doesn't specify whether this requires authentication, has rate limits, returns real-time or cached data, or what format the output takes. The description lists content categories but doesn't describe behavioral traits like performance characteristics or access requirements.

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 extremely concise and well-structured in a single sentence. It front-loads the core purpose ('Return an overview of your knowledge base') followed by specific components in a clear list format. Every word earns its place with no redundancy or unnecessary elaboration.

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 has 0 parameters, 100% schema coverage, and an output schema exists, the description's job is simplified. It adequately describes what the tool returns (an overview with specific components). However, for a reporting tool with no annotations, it could benefit from more behavioral context about data freshness, authentication needs, or output format since the output schema isn't visible in the evaluation 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?

The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description appropriately doesn't discuss parameters since none exist. It focuses on what the tool returns rather than what it accepts, which is correct for a parameterless tool.

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's purpose: 'Return an overview of your knowledge base' with specific components listed (capture counts, top tags, open questions, key insights, date range). It uses a specific verb ('Return') and resource ('knowledge base'), but doesn't explicitly differentiate from sibling tools like 'knowledge_progress' or 'journal_health' which might provide related metrics.

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 provides no guidance on when to use this tool versus alternatives. With sibling tools like 'knowledge_progress', 'journal_health', and 'get_breakthroughs' that might provide overlapping or complementary metrics, there's no indication of when this overview tool is preferred or what distinguishes it from other reporting 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?

No annotations are provided, so the description carries the burden, and the verb 'Report' plus the enumerated fields make it clear this is a non-mutating informational read with no arguments. It stops short of stating side-effect or permission characteristics explicitly, but for a zero-parameter local version lookup there is little behavioral risk left undisclosed.

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

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

Two short sentences, fully front-loaded with the purpose followed immediately by the motivating use case. No filler and nothing redundant.

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

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

A zero-parameter tool with an output schema and no annotations; the description explains what data is returned and why you would call it, which is everything an agent needs to select and invoke 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?

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The description instead specifies what is reported (ksj-mcp, mcp, pydantic, python), which is a small useful addition.

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: 'Report the running ksj-mcp version and key dependency versions (mcp, pydantic, python).' No sibling tool covers version reporting, so it is trivially distinguishable from the list.

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

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

Explicitly names the use case: 'Use this to confirm an install or upgrade actually took effect.' This gives a clear context for invocation. It does not name alternatives or exclusions, but no sibling tool competes for this purpose, so the gap is minor.

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

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

With no annotations, the description carries the burden and does well: it discloses the real side effects of the mutation — re-parsing stored text with the correct template's parser and rebuilding tags and connections. It omits permissions, reversibility, and whether a prior ID is overwritten, but the key behavioral consequence is stated.

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 purpose, then usage condition, then side effects, then args. Every sentence adds information and none is redundant padding; the structure maps cleanly to how an agent would read 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?

An output schema exists so return values need not be described. For a mutation tool with no annotations, the description covers purpose, trigger, side effects, and all parameter semantics — 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 coverage is 0%, so the description must fully compensate and it does: capture_id is explained as the numeric ID shown as '#N in upload output', template_id is given concrete examples ('RC-007', 'DC-003'), and volume is clarified as optional with '0 = keep'. All three parameters gain meaning beyond the bare 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: 'Assign or fix the template ID of a stored capture.' The scope is narrowed to UNIDENTIFIED pages or misread IDs, which distinguishes it from upload_capture and correct_ocr in substance, though it does not name those siblings explicitly.

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

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

Gives an explicit trigger condition: pages stored as UNIDENTIFIED (no readable template ID at upload time) or where the ID was misread. This is clear when-to-use guidance, but it never states when NOT to use it or which sibling (correct_ocr, promote_capture, set_volume) is the alternative for adjacent cases.

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 discloses collision handling (skip on (volume, template ID) match), the no-overwrite guarantee, and that user-asserted edges are restored while derived connections are rebuilt. It omits auth/permission requirements, size limits, and error/partial-failure behavior, keeping it below a 5.

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

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

Three tight sentences, front-loaded with the purpose and the critical non-destructive guarantee before the finer edge-handling detail. The Args block is minimal and the only parameter is one line.

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

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

An output schema exists, so return values need not be explained, and the description covers the semantic behavior an import tool needs. Remaining gaps (auth prerequisites, failure/rollback semantics for a partially-applied import) are minor but real for a mutation-class tool with no annotations.

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

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

Schema coverage is 0%, so the description must compensate. It does: file_path is documented as a path to a file produced by export_backup, with the expected ksj-export-v1 JSONL format implied, which adds real constraint beyond the bare string type in 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 (Restore) plus the exact resource and format (ksj-export-v1 JSONL backup into the knowledge base), and explicitly ties the input to a named sibling (export_backup). An agent can distinguish this from export_backup/export_html without opening any schema.

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

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

The description makes the trigger scenario clear (restoring a backup file produced by export_backup) and states the additive, non-destructive contract. It does not spell out when NOT to use it or any alternative import path, so it stops short of explicit 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, the description carries the full burden. It does add one genuinely useful behavioral fact — hand-written captures only, AIEX entries excluded so metrics aren't inflated — which an agent could not infer elsewhere. However, it says nothing about whether the call is read-only, whether it's expensive to compute, or whether results are cached/stale, so the safety and cost profile remains undisclosed.

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 one-line purpose followed by a scannable bullet list of tracked metrics and a closing statement of what is returned. Every line carries information; the only mild cost is that the metric list is longer than strictly needed for 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?

An output schema exists, so the description need not detail return values, and it wisely restricts itself to a one-line summary of the return. For a zero-parameter read tool, the description plus output schema gives an agent enough to call it correctly; only the lack of any comparison to similar stats tools leaves a small 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to clarify or compensate for on this dimension.

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 concrete deliverable — a KPI dashboard plus coaching recommendations over journal practice — and enumerates exactly which metrics it computes (capture velocity, insight velocity, days since Review, unanswered questions, synthesis activity, template balance). That enumeration distinguishes it from generic siblings like get_stats, though it never names those siblings explicitly.

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

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

The content implies when the tool is useful (periodic practice check-ins, coaching), but there is no explicit when-to-use statement, no exclusions, and no routing against near-neighbors such as get_stats, knowledge_progress, or get_breakthroughs. Usage is left to inference from the KPI list.

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 full burden for behavioral disclosure. It describes what the tool does (track progression and show status movement) but lacks details on output format, data freshness, rate limits, authentication needs, or whether it's read-only or has side effects. The mention of 'over time' hints at historical data, but this isn't elaborated.

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

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

The description is well-structured and appropriately sized, with a clear purpose statement followed by parameter details. Every sentence adds value, though the second sentence could be slightly more concise by combining ideas about status progression.

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 has an output schema (which handles return values), one parameter with good description coverage, and no annotations, the description is reasonably complete. It explains the tool's purpose, parameter usage, and context, though it could benefit from more behavioral details like data scope or limitations.

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 description adds significant value beyond the input schema, which has 0% description coverage. It explains the 'topic' parameter's purpose (to filter by topic tag), provides an example ('calculus'), clarifies it's optional, and specifies that leaving it blank shows all topics. This fully compensates for the schema's lack of documentation.

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's purpose: 'Track Knowledge Status progression across your Review (REV) entries' and explains it visualizes how topics move through status levels over time. It specifies the resource (REV entries) and verb (track progression), though it doesn't explicitly differentiate from sibling tools like 'get_stats' which might also provide progress-related data.

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 usage context by mentioning 'REV entries' and 'Knowledge Status field', suggesting it's for tracking learning progress in a review system. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'get_stats' or 'journal_health', nor does it mention prerequisites or 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, the description carries the full behavioral burden and does convey substantive detail about what is inspected and why it matters. It never states, though, whether the operation is read-only or non-destructive, nor how its findings are surfaced, leaving an agent to infer the safety profile.

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 core purpose and then the checks, with the parameter note clearly separated. The prose is slightly colorful ('silently rots', 'entrenches errors') but mostly earns its place and stays readable.

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

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

An output schema exists, so return values need not be explained, and the single optional parameter is covered. The main gap is the absence of any read-only/destructive statement and of routing versus the similar audit siblings, but the essentials are present.

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

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

Schema description coverage is 0%, so the description must compensate and it does: it explains stale_question_days as the age at which an unanswered '?' question is flagged, and confirms the default of 30. Meaning is added beyond the bare integer in 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 action (a knowledge base health check / lint) and enumerates exactly the failure modes it detects: orphan captures, superseded claims, unresolved contradictions, stale questions, and tag fragmentation. This is concrete enough to distinguish it from nearby diagnostic siblings like journal_health or audit_knowledge_status.

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 frequency guidance ('run it occasionally') and a rationale (a never-linted base entrenches errors), which implies when to use it. However, it never names an alternative or explains when NOT to run it, despite several plausibly overlapping diagnostic siblings in the list.

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 load and does well: it discloses that tag may be empty when entry_type/wa_reason is given, that the same prefix character means different things on DC vs RC/SYN/REV pages, and that role is the disambiguator. It does not discuss permissions, ordering, or result limits, but an output schema exists so return format is covered elsewhere.

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 one-line purpose before any examples, and every example line demonstrates a materially different invocation rather than restating the same call. Somewhat long, but each line earns its place as parameter documentation.

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?

Five optional parameters, no required ones, no annotations, and a 0%-coverage schema — yet the description supplies the values, defaults behavior, and interaction rules for all five. With an output schema handling the return shape, an agent has everything needed to invoke this 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 0% (the schema declares only titles/types, no enums), so the description must compensate and it does: it explains that tag is given without the prefix character, enumerates the prefix characters, enumerates entry_type values (RC, SYN, REV, DC, ISO, WA, AIEX), lists all wa_reason values, and gives the full role vocabulary.

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?

Opens with a specific verb+resource+scope: browse captures carrying a specific tag, with no text query. It also clearly carves out the secondary mode (browsing by entry type / Wild Art queue), which separates it from tag-agnostic siblings like search_captures.

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 'no text query required' framing plus ten worked examples tell the agent exactly which scenario maps to which argument combination, and 'Use this to find every note related to a topic, source, question, or insight' states the intent. It stops short of explicitly naming search_captures as the alternative for text queries, so it falls just 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 so: accept-by-default means nothing is rejected and nothing is overwritten, unparseable template/page collisions fall back to a Wild Art entry with a recorded reason, and force=True replaces rather than duplicates. These are non-obvious side effects an agent must know before calling.

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 purpose and the primary-path routing before the behavioral caveats and the Args block. It is long, but nearly every sentence carries distinct operational information (faithful transcription, tag handling, accept-by-default). Slightly dense rather than bloated.

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

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

An output schema exists, so return values need not be detailed, and the description still notes the return mirrors upload_capture including detected connections. For a 6-param mutation tool with zero annotation coverage, all behavioral and parameter gaps are filled.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all six parameters with defaults and semantics: volume 0 = automatic with volume-wins-over-current_volume precedence, force replacement vs. WA-with-id_conflict default, wa_reason accepted values, and free-text wa_detail. This goes well beyond the bare 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?

Opens with a specific verb+resource: 'Store a journal capture from transcribed text', and immediately positions itself against the sibling upload_capture as the PRIMARY path for handwritten pages. An agent can distinguish this from upload_capture, correct_ocr, and bulk_upload without opening any schema.

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

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

Gives explicit routing: prefer this over upload_capture whenever the user can show you the page, because assistant vision beats local OCR. It also spells out when to pass template_id='ISO-001', when to pass 'WA', and when to hand-file with wa_reason='loose_capture'. When-to-use, when-not, and alternatives are all present.

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 burden alone. It discloses one useful behavioral constraint — the depth cap of 4 — but says nothing about whether the call is read-only, how large the result may get, or performance implications of deeper walks. As a read-style graph query with an output schema, this is a modest gap rather than a severe one.

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

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

One front-loaded sentence states the tool's essence, followed by a compact args block. Nothing is padded, and the core definition appears before any parameter detail.

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 an output schema present, return values need no explanation, and the description covers purpose and both parameters adequately. The remaining gap is routing guidance relative to sibling graph tools, which is not 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 description coverage is 0%, so the description must compensate, and it does: both parameters are explained, and the depth parameter gains the max-4 constraint that does not appear in the schema at all. This is more than the schema alone provides, though it omits what happens at the boundary or how depth interacts with sparse clusters.

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 resource and operation: the subgraph within N hops of a capture in the connection graph, described as its 'local knowledge cluster'. This is clearly distinguishable from most siblings, though it never explicitly contrasts itself with the related find_connections, surface_connections, or find_path 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?

There is no explicit guidance on when to use this tool versus the connection-related siblings, nor any prerequisites or exclusions. The agent must infer from the phrase 'local knowledge cluster' that this is a breadth-oriented traversal rather than a pairwise or path query.

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 thoroughly: it says exactly what is preserved (#id, text, image, asserted links), what metadata is carried over (promoted_from, wa_reason, wa_detail), that a page-ID conflict changes NOTHING until the caller decides, that IDs are never auto-renumbered, and the precise side effect of force (holder moved to Wild Art, all @references re-resolve to this capture).

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?

Purpose, conflict behavior, and the force warning are front-loaded before the Args block, and every sentence carries operational information. It is long, but the length is justified by the mutation's complexity; some of the WA-history detail could be trimmed.

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

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

An output schema exists, so return formatting need not be described; the description instead covers everything an agent needs to call this safely — conflict handling, ID/volume resolution, and the reference-rewriting consequence of force. Complete for a complex mutation with 0% schema coverage and no annotations.

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

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

Schema description coverage is 0%, so the description must compensate, and its Args block defines all five parameters with defaults and exact semantics — capture_id as #N, the target_type enumeration, target_page_id fallback to claimed_page_id, volume's 0 = existing/current-volume rule, and force's danger and side effects. This adds substantial meaning beyond the bare 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 states a specific verb and resource — moving a Wild Art entry to its proper type after review — and enumerates the valid targets (RC, SYN, REV, DC, ISO). It clearly distinguishes the WA-promotion action from generic capture handling, though it never names a sibling tool it should be preferred over.

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?

Context for use is clear: this happens 'after review' on a WA entry, and it explains when target_page_id may be omitted (when the page was read with a claimed_page_id of the target type). force carries an explicit when-to-use caveat ('Only use it when you are sure the current holder is the misfiled one'), but no alternatives from the sibling set are named.

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 a good job: it declares idempotency ('running it twice produces the same graph') and explains the concrete effect on dangling references. It stops short of disclosing cost/scale on large graphs or whether manually asserted connections (see assert_connection) are preserved or overwritten.

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

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

Three sentences, front-loaded with the core action, then the trigger conditions, then the idempotency guarantee. The RC-015 example is concrete and earns its place rather than 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?

An output schema exists, so return values need no explanation. But for a whole-graph rebuild with coexisting mutation tools like assert_connection and manual_capture, the description should say whether manually asserted edges survive the rebuild — an agent cannot safely decide to run this without that answer.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level meaning is missing.

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: 'Re-derive the entire connection graph from current tags and text.' This clearly distinguishes it from read-oriented siblings like find_connections, surface_connections, and neighborhood, which query the graph rather than rebuild it.

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

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

Gives concrete trigger conditions: after correcting OCR, identifying previously-unidentified pages, or uploading pages out of order, and explains why (a dangling reference gains its edge). It does not name when NOT to run it or point to an alternative tool, so it falls just short of the top band.

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 behavioral burden. It discloses a useful behavioral constraint ('search matches terms that appear in the journal text' and natural-language queries work), but says nothing about ranking, pagination, result limits, or performance characteristics of a search operation. Some value added, but significant behavioral gaps remain.

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 and generally well-structured, but the four-line query example block is lengthy, and the parameter list is formal (Google-style 'Args:') where the schema already names each field. Some repetition between the intro sentence and the args adds bulk without new guidance.

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?

Output schema exists, so return values need not be explained. The description covers purpose, usage, routing to a sibling, and all six parameters with the enum values. The main remaining gap is behavioral detail on search semantics (ranking, limits) which annotations also don't cover. Strong for a search tool overall, with room for behavioral specifics.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: each parameter is explained with purpose and examples, including the wa_reason enum values (id_conflict, unrecognized_template, ocr_low_confidence, etc.) and entry_type codes. This adds substantial meaning beyond the bare schema. It stops short of full coverage (e.g. how tag_filter matches, date format edge cases), 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?

Opens with a specific verb+resource: 'Search all journal entries by concept, keyword, or phrase.' It further scopes by naming the coverage ('across every template type') and explicitly distinguishes itself from the tag-browsing sibling list_by_tag. An agent can tell exactly what this tool does vs neighbors.

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 ('whenever the user asks to find notes, recall something they wrote, or explore a topic') and an explicit alternative with its selecting condition ('For tag-only browsing without a text query, use list_by_tag instead'). This is the strongest form of routing 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 largely meets it: it discloses sentinel semantics (0 / empty = leave unchanged, '*' = all), the read-only no-arg invocation, and the important scope exception that journal_health and knowledge_progress always see all volumes. It does not cover persistence, permissions, or reversibility, but the operational traits that matter for correct invocation are 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?

Front-loads the purpose, then explains the volume concept, then documents each argument — a logical order with no wasted filler. The conceptual paragraph on multi-journal continuity is arguably longer than strictly necessary but it prevents an agent from mis-modeling volumes as independent.

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 two-optional-parameter configuration tool with an output schema already supplied, everything an agent needs is present: purpose, invocation modes, sentinel values, and scope interactions with KPI tools. Nothing material is left for the agent to guess.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: current_volume is defined as the target for NEW captures with 0 meaning unchanged, and active_volumes is defined as the read scope with '*' and comma-list syntax plus empty meaning unchanged. Both parameters get meaning the schema alone cannot supply.

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?

Names a specific verb+resource (configure journal volumes) and states exactly what it governs: which book new captures land in and which books search/browsing can see. No sibling tool touches volume configuration, so it is trivially distinguishable.

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 concrete activation conditions: 'Set current_volume once when starting a new book' and 'Call with no arguments to just see the current settings.' It also scopes the effect of active_volumes against other tools. It stops short of explicitly naming an alternative tool, but none of the siblings performs this function.

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 of behavioral disclosure. It mentions scanning and identifying clusters but doesn't describe how the tool behaves: e.g., whether it returns a list of topics with metadata, how it handles large datasets, or if it requires specific permissions. For a tool with no annotation coverage, this leaves significant gaps in understanding its 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?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, and the second provides parameter details. There is no wasted text, and the structure is clear and efficient, making it easy for an agent to parse 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?

Given the tool has an output schema (which likely describes return values), the description doesn't need to explain outputs. However, with no annotations and only one parameter, the description covers the purpose and parameter semantics adequately but lacks behavioral details (e.g., how clusters are identified, performance considerations). It's minimally viable but could be more complete for a clustering tool.

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

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

The description adds meaningful context for the single parameter 'min_captures', explaining it as 'Minimum number of RC entries on a topic to flag it' and noting the default value. Since schema description coverage is 0% (the schema only provides title and type), the description compensates well by clarifying the parameter's purpose and default, though it could add more about valid ranges or effects.

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's purpose: 'Scan your Rapid Capture entries and identify topic clusters ready to be synthesized into a SYN page.' This specifies the verb ('scan', 'identify'), resource ('Rapid Capture entries'), and outcome ('topic clusters ready to be synthesized'). However, it doesn't explicitly differentiate from sibling tools like 'search_captures' or 'find_connections', which might have overlapping functionality.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., having Rapid Capture entries), exclusions, or comparisons to sibling tools like 'search_captures' or 'find_connections'. The agent must infer usage context solely from the purpose statement.

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: it discloses the read-only nature ('does NOT write to the database'), the hard precondition with no override, the decline-and-redirect behavior, and the meaningful independence guarantee (the scan never reads the SYN page before producing its map). These are non-obvious behavioral traits an agent could not infer from schema or siblings.

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 core action and then layers preconditions and params efficiently; most sentences earn their place. It is somewhat long, and the inline reference to an internal markdown filename (ksj2_documents/SYN_companion_decision_optionB_2026-08-03.md) adds little value for an agent choosing the 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?

For a gated, multi-step tool with a precondition, params, and a downstream commit step, the description covers everything an agent needs: when it may run, what it returns at a high level, and what must happen after. An output schema exists, so return-value detail is appropriately left out.

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

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

Schema description coverage is 0%, so the description must compensate fully, and it does: it defines syn_template_id as required with decline behavior, entry_ids as optional comma-separated RC IDs required only when the cluster can't be auto-resolved, days as a narrowing window with 0 = no filter, and depth's three tiers plus the user's 'more on this one' escape hatch. This adds meaning well beyond the bare typed properties.

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 (scan/compare) and resource (Rapid Capture cluster behind a Synthesis page), and precisely scopes the operation as 'prepare a structured dialogue comparing what the scan found against what the page found.' It is clearly distinguishable from siblings like suggest_synthesis and commit_distillation, which it names directly.

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 precondition ('runs AFTER a SYN page exists — never before'), states there is no override flag, and names the fallback (suggest_synthesis()) when the precondition fails. It also supplies concrete trigger phrases and clarifies that commit_distillation() is the required follow-up after user approval.

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 does well: it discloses accept-by-default (never rejected), the WA fallback with reasons recorded, and that force replaces an existing capture without overwriting otherwise. It omits permission/auth requirements and any rate or size 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?

Content is front-loaded with purpose then fallback semantics and args. Some prose is slightly verbose, but each section serves a distinct need, and the structure is easy to scan.

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 multi-step mutation tool with no annotations, the description covers the pipeline, fallback behavior, and all parameters thoroughly. Output schema exists so return details need not be explained, and the added note about the strongest connection is a useful touch.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it documents all five parameters including image_path formats, the exact meaning of force, the volume=0 automatic resolution rule, and valid wa_reason values. This adds substantial meaning beyond the bare 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 states a specific verb (process/upload a journal page photo) and enumerates the full pipeline: OCR, template parsing, tag extraction, storage, image copy, and connection detection. This distinguishes it clearly from siblings like manual_capture, bulk_upload, and correct_ocr.

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 conditional usage: use wa_reason='loose_capture' for off-journal items and force=True to replace an existing capture. It also routes WA follow-up to list_by_tag and promote_capture. It stops short of explicitly stating when to pick this tool over manual_capture or bulk_upload.

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