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

With no annotations, the description carries the full burden and delivers: it discloses that insights for the same figure are appended (not overwritten), that the note backlinks the paper, and that the note is sized to stay within the search index window. The recommended structured-fact format ('panel C: IC50 = 2.3 µM') is a concrete behavioral convention the agent could not infer from the schema.

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

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

Front-loaded with the purpose, then workflow guidance, then an Args block — a clean hierarchy where each sentence carries information. It is somewhat verbose with the caching rationale repeated, but nothing is filler. Slightly trimmer would reach a 5.

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

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

For a three-required-parameter mutation tool with no annotations, the description covers purpose, prerequisites, storage semantics, and every parameter, and an output schema already exists so return values need no explanation. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does via an explicit Args section for all three parameters: note_path (vault-relative path of the source paper note), fig_index (0-based, cross-referenced to search_figures/read_figure), and insight (the fact/observation). Every parameter gains meaning beyond its bare name and type.

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: 'Save a read-time insight about a figure as an atomic vault note.' It distinguishes itself from general note tools like append_to_note by scoping the artifact to figure-derived insights that backlink the source paper. An agent can tell what this produces without opening the schema.

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

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

Explicitly states when to use it — 'AFTER you have loaded a figure (read_figure) and reasoned out something worth keeping' — naming the prerequisite sibling tool and the trigger condition. It also gives the payoff rationale (future questions answered from text without re-loading the image). It does not explicitly contrast against the closest alternative (append_to_note), which keeps it from 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 behavioral burden. It discloses key append semantics: existing text is never lost, and content is added after a blank line at the end of the file. It does not cover permissions, error cases, or atomicity, which would be needed for 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?

The description is front-loaded with the tool's purpose, followed by safety and usage guidance, and then a compact Args section. Every sentence earns its place with no redundancy.

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

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

Given the tool's low complexity, no annotations, and the presence of an output schema, the description covers what an agent needs: purpose, usage, safety, and parameter details. It omits only minor context like permissions or failure modes, which is acceptable but not perfect.

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 well: path is explained as a relative path from the vault root with a concrete example, and content is explained as text appended after a blank line at the end of the file, adding behavior 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?

The description states a specific verb and resource: 'Append content to the end of an existing note.' It also distinguishes this tool from the sibling update_note by noting it is safer because existing text is never lost, allowing an agent to select correctly without checking schemas.

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

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

It gives clear usage context ('Use for adding progress updates, new findings, or extra sections') and names the alternative update_note as a less safe option. It does not explicitly say when not to use it, but the alternative and conditions are strongly implied.

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

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

Annotations already declare readOnlyHint, non-destructive, idempotent, and closed-world, so the safety profile is covered. The description's 'without changing the vault' reinforces that but adds little beyond the annotations. It gives no detail on how issues are categorized or how many categories to expect.

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 purpose sentence followed by a tidy Args block; no wasted sentences. The '1..500' and '1..90' ranges duplicate the schema's min/max, a small redundancy.

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

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

Output schema exists, so return-value explanation is unnecessary, and the description covers the non-mutation behavior and all three parameters. It is nearly complete for a read-only audit, with only the meaning of 'issue category' left implicit.

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 carry the load, and it does via the Args block: scope explains which records are audited, limit explains 'max results per issue category', and stale_after_days explains the staleness threshold. Only minor value-add remains missing (e.g. what counts as an 'issue').

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: auditing 'article records and social-source state' without mutating the vault. An agent can identify the operation clearly, though it does not explicitly distinguish itself from a neighboring sibling like query_audit_log.

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 / when-not-to-use guidance and no named alternative. The scope parameter implies some context (articles vs social vs all), but nothing tells an agent when to reach for this tool instead of search_articles or query_audit_log.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds that the result is scoped to the caller's own identity and includes a role, which is useful, but it says nothing about what happens on an unauthenticated call or how the UUID should be interpreted.

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

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

A single front-loaded sentence with no filler. Every word carries meaning and nothing is redundant with the title or schema.

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

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

An output schema exists, so the description need not explain return values, and it already names the two fields returned. For a trivial zero-parameter identity tool this is nearly complete; only the absence of any when-to-use cue keeps it short of a 5.

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 for a no-parameter tool applies.

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

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

States a specific verb ('Return') and a specific resource (the authenticated caller's canonical EP UUID and current role). No sibling tool overlaps with this identity-lookup purpose, so an agent can distinguish it immediately.

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

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

Usage is implied by the self-referential scope ('the authenticated caller's'), which is enough for a zero-parameter identity probe, but the description never explicitly says when to call it (e.g. at session start, to resolve the acting user's ID) or names any alternative.

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: resumability, per-image commit boundaries, failure-requeue behavior, the 20/20 bound, and the guarantee that paid fallback is impossible. These are exactly the operational traits an agent needs before triggering a model-backed batch job.

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 behavior and the binding constraint before the arg list. The Args block largely mirrors the schema and could be trimmed, but each line carries a non-obvious 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?

An output schema exists so return values need no prose, and for a bounded, resumable, mutation-style batch tool the description covers scope, safety, limits, and failure semantics sufficiently to call it correctly blind.

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: note_paths are vault-relative, dry_run explicitly means no model calls or writes, and both limits are bounded 1-20. This adds real meaning over 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?

Names a specific verb+resource ('Fill empty OCR/description fields') and pins the mechanism ('only the configured local VLM'), which cleanly separates it from siblings like extract_figures_for, reconcile_figures, and annotate_figure that also touch figures.

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 conveys the precondition (SB_VISION_BACKEND=local-only is mandatory) and the dry_run preview path, but never states explicitly when to reach for this tool over reconcile_figures or extract_figures_for, leaving the routing inference to the agent.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses key effects: source notes get status='consolidated', are deprioritized in context, and the default dry_run=True prevents accidental mutation. It does not mention required permissions, reversibility, or rate limits, but covers the main side effects.

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

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

Front-loads the core action, then details the process in a logical flow, and ends with a clear safety note and parameter list. Every sentence adds value without redundancy.

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

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

Given 2 parameters, no annotations, and an output schema (which handles return values), the description provides sufficient context: it explains what the tool does, the side effects, the default safety behavior, and parameter meanings. Nothing critical is missing for an agent to 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?

Schema description coverage is 0%, so parameters lack structured descriptions. The description compensates by providing defaults and brief semantics for both parameters (threshold as cosine similarity threshold, dry_run as showing clusters without consolidating). This is adequate but not rich; it doesn't explain threshold units or acceptable ranges beyond the default.

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 (consolidate clusters of semantically similar notes) and details the mechanism (cosine similarity grouping, synthesis via Gemini CLI, output to 20-areas/consolidated/). This clearly distinguishes it from siblings like find_related_notes or search_notes, which merely search rather than merge.

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 notes the default dry_run=True and advises inspecting clusters before committing, which is a clear usage cue. However, it doesn't name alternative tools (e.g., find_related_notes) or state when not to use this tool, leaving some routing ambiguity.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the exact computation method, top-5 neighbor selection, frontmatter write behavior, force-overwrite semantics, and that no API or model calls are made. This gives an agent a clear picture of side effects and local-only execution.

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 purpose and mechanism, then structured into clear Args and Returns sections. Every sentence adds operational value, and there is no redundant 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?

The description is largely complete for a two-parameter mutation tool with an output schema and no annotations. It documents parameters and side effects thoroughly, though it omits prerequisites such as requiring existing embeddings in vault.db and does not position the tool relative to its 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 for both parameters. It does: note_path is defined as a relative path to a single note, with empty string meaning all notes lacking neighbor_keywords, and force is defined as overwriting existing values with the default being to skip.

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: enrich notes with neighbor_keywords and cluster_topic derived from embedding similarity. It clearly distinguishes the mechanism by explaining cosine similarity and top-5 neighbors, but it does not explicitly differentiate this tool from similarly named siblings such as expand_semantic_keywords_tool.

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 explains parameter behavior, including that an empty note_path processes all notes without neighbor_keywords and that force overwrites existing data. However, it does not say when to choose this tool over alternatives, nor does it name any alternative for semantic keyword expansion or related-note discovery.

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 succeeds: it discloses that keywords are written into frontmatter, that the FTS index is rebuilt (a real side effect), that existing keywords are skipped unless force=True, and the LLM backend fallback order. It omits auth/permission requirements and cost/latency implications of invoking LLM CLI backends.

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, then structured Args/Returns sections. Every line is informative, though the parenthetical backend-priority detail and pointer to llm_cli.py's docstring are marginally more than an agent needs for invocation.

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-parameter batch tool with no annotations, the description covers side effects, skip/force semantics, and output shape (redundantly, since an output schema exists). It is nearly complete, missing only permission/auth context that an agent might need before running it.

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

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

Schema coverage is 0%, so the description must compensate, and it fully does: note_path is given semantics, an example format, and the empty-string behavior; force is given its exact effect and default. Nothing about either parameter is left undocumented.

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

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

States a specific verb+resource: 'Batch-extract or refresh semantic_keywords for notes.' An agent can immediately tell this operates on note frontmatter keywords at batch scale. However, it never differentiates itself from the existing sibling enrich_neighbor_keywords_tool, leaving the sibling boundary to inference.

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 only implied through parameter behavior ('Leave empty to process all indexed notes missing keywords'), which hints at when the no-arg mode applies. There is no explicit guidance on when to choose this over enrich_neighbor_keywords_tool or extract_rules_tool, and no stated 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?

No annotations are provided, so the description carries the full burden. It discloses only that the trigger is manual; it does not say whether extraction writes new files, overwrites existing figures, requires network/LLM access, or has cost/rate implications. For a mutation-style trigger with zero annotation coverage, this is a significant gap.

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

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

Two short lines, front-loaded with the action and then the one argument with an example. The 'Args:' block is somewhat boilerplate but earns its place by supplying the path format.

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, and the single parameter's format is covered. What remains missing is any behavioral context for a side-effecting trigger (side effects, permissions, failure modes), leaving the definition only minimally complete.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains note_path is a relative path within the vault and gives a concrete example ('30-resources/my-article.md'). That is meaningful semantics beyond the bare string type, though it does not state behavior for missing files or wrong paths.

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 ('trigger figure extraction') scoped to 'a saved article.' The word 'Manually' implies a contrast with automatic extraction, which helps, but it does not name or distinguish itself from figure-related siblings such as reconcile_figures or backfill_figure_text.

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?

'Manually trigger' implies the tool is used when automatic extraction did not occur, which is implied usage guidance. There is no explicit statement of when to prefer this over reconcile_figures, backfill_figure_text, or restore_missing_pdf_images, nor any precondition or exclusion.

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 must carry the behavioral burden. It discloses the key side-effect (writing to memory/rules.md) and the downstream effect (rules auto-injected at the top of every get_context() call), which is valuable context beyond the schema.

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

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

Front-loads the purpose and file target, followed by the important downstream effect and parameter details. The two-sentence preamble is efficient, though the Args block uses slightly more space than strictly necessary.

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

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

Given an output schema exists, return values needn't be explained. The description covers what the tool does, where it writes, the batch eligibility criteria, and param behavior — enough for an agent to invoke it correctly despite 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%, but the one parameter is well-explained: note_path accepts a path like 'decisions/my-note.md' and an empty value triggers batch mode with clear eligibility rules. The description compensates for the lack of schema descriptions.

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

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

States a specific verb (extract) and a precise resource (L3 declarative rules from high-access notes into memory/rules.md). The description makes clear this writes to a specific file and what kind of rules are involved, distinguishing it from siblings like read_note or search_notes.

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?

Specifies the eligibility criteria for batch mode (access_count >= 5, not extracted in last 90 days) and the single-note mode. However, it doesn't explicitly state when to prefer a single-note extraction over a batch run, or name alternatives like consolidate_tool.

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 disclose the mechanism (cosine similarity on stored embeddings) and an important edge case (returns a message when no embeddings exist), which is genuinely useful. But it omits prerequisites such as whether notes must be indexed/synced first, and says nothing about permission or side-effect 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 in one sentence, then uses compact bulleted examples and an Args/Returns block. Slightly listy, but each section carries information with little 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?

Output schema exists, so the return-value description is a bonus rather than a necessity. For a 3-param read tool with moderate complexity, the description covers mechanism, parameters, defaults, and the no-embeddings fallback; only indexing prerequisites are absent.

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 path format with a concrete example, limit as max results with default 5, and threshold as cosine similarity 0–1 with default 0.7. It stops short of explaining interaction between limit and threshold (e.g., filtering order), so not a full 5.

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

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

States a specific verb+resource ('Find semantically related notes for a given note') and pins down the input as a vault-relative path. This distinguishes it from siblings like search_notes (keyword search) and query_graph (graph traversal) by naming the similarity mechanic up front.

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?

Offers two concrete 'useful for' scenarios (finance stock reports, knowledge overlap discovery), which imply usage. However, it never states when to prefer this over search_notes or query_graph, nor any exclusions, so a routing decision still requires inference.

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

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

No annotations are provided, so the description must carry the behavioral burden. It says the tool returns the manual contents and is intended for remote sessions, but it does not mention authentication needs, side effects, idempotency, or whether the call is safe/read-only. For a simple getter this is adequate but incomplete.

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 tool's purpose and usage guidance in a compact structure. The 'Returns:' section repeats what the output schema already provides, which is mildly redundant, but the overall description remains 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?

The tool is low-complexity and has an output schema, so the description need not explain the return value. It covers what the tool does and when to use it, though the absence of annotations leaves a small gap around permissions or execution 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 zero parameters, so per the rubric the baseline is 4. The description adds no parameter details because there are none to add.

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: 'Return the full AGENTS.md operating manual for AI agents.' This clearly distinguishes the tool from data-query siblings like get_context or auth_context, but it does not explicitly name or contrast any sibling, 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?

Gives an explicit trigger ('Call this at the start of a remote session') and the condition that selects it ('when AGENTS.md cannot be read from the filesystem'). No alternative tool is named, but the condition implicitly rules out filesystem access, which is sufficient guidance.

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

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

No annotations exist, so the description carries full behavioral burden. It discloses the payload shape, goals + top-20 recently active notes, which is useful. It does not state whether the call is idempotent or side-effect free, so a small gap remains.

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

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

Two sentences with zero waste, and the payload summary is front-loaded ahead of the call-to-action. Nothing to trim.

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. The description covers purpose and timing for a zero-arg orientation tool. A note on freshness or cost would make it complete.

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

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

Zero parameters means the baseline is 4. The description correctly implies no arguments are needed, matching the empty schema. No compensating detail is required.

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: load session context comprising current goals plus the 20 most recently active notes. This is more precise than a tautology, but value would rise with explicit routing against siblings like get_decisions or read_note.

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 with a specific timing rule: 'Call this at the start of every session to orient yourself.' This is a direct, unambiguous instruction that no sibling tool provides.

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

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

No annotations are provided, so the description carries the full burden. 'Get' implies a read-only operation and it usefully discloses the default behavior when project is empty, but it says nothing about permissions, result limits/pagination, or whether the vault must be initialized first. Modest disclosure for a zero-annotation tool.

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

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

One sentence of purpose followed by a compact Args block; the core behavior is front-loaded with no filler. The docstring-style 'Args:' formatting is slightly mechanical but costs nothing in clarity.

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 documented. Still, for a tool with no annotations, it omits obvious operational details such as result limits or ordering, leaving the agent with a minimally viable definition.

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: it names the 'project' argument, marks it optional, states it filters by project name, and explains that an empty value returns all decisions. Only the accepted matching format (exact name vs substring) is left unspecified.

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: 'Get decision records from the vault.' An agent knows exactly what it retrieves, though the description never differentiates this retrieval from sibling search tools like search_notes or query_graph, so it stops short of a 5.

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

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

No when-to-use guidance and no alternatives named. The only usage information is the parameter's fallback behavior ('If empty, returns all decisions'), which explains filtering, not tool selection against the many sibling retrieval 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 well: it discloses the read-only diagnostic nature, the six items inspected, and the OK/WARN/ERROR output format. It stops short of stating that it makes no mutations or that it may be slow when the vault or embedding server is unreachable.

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 purpose in the first sentence, then a compact list of checks, then the return format. Every clause carries information an agent can act on; there is no filler.

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

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

For a zero-parameter diagnostic with an output schema already describing the report structure, this covers what the agent needs to decide and call the tool. The only gap is the absence of guidance on when this is preferable to narrower siblings like index_stats.

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, which is the baseline 4 case; the description correctly does not invent argument semantics, and the empty schema needs no compensation.

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

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

States a specific verb+resource ('Diagnose second-brain system health') and then enumerates the exact checks performed, so an agent can distinguish it from operational siblings like index_stats, sync_index, or auth_context 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?

Use is implied by the diagnostic framing, but there is no explicit when-to-use guidance, no statement of when-not-to-use it, and no routing to alternatives such as index_stats or query_audit_log for narrower diagnostics.

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 must carry the behavioral load; the phrasing 'Show' implies a non-mutating read, and it does disclose what categories of data come back. However, it says nothing about cost, freshness, or what happens if the index is absent/uninitialized.

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

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

A single front-loaded sentence that names the resource first and then lists the three payload items with no filler.

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

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

For a zero-parameter read-only tool with an output schema that already documents the return shape, the description supplies everything an agent needs to decide to call it. Only minor context (e.g., freshness or failure modes) 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

States a specific verb (Show) and resource (vault index statistics) and enumerates the content returned (total notes, breakdown by type, DB location). It is clearly a read-only reporting tool, but it does not explicitly distinguish itself from neighbors like health_check or sync_index, which could plausibly also report index state.

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

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

No guidance on when to call this versus alternatives such as health_check, sync_index, or query_audit_log. There is no mention of prerequisites (e.g., vault must be initialized) or when the result matters.

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 it does disclose the key behavioral trait: it is idempotent and non-destructive ('only creates missing items, never overwrites existing files'). It stops short of stating permission/auth requirements or whether any output messaging signals partial repair.

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 short sentences, each earning its place: purpose first, then the safety guarantee, then the timing cue. No waste and front-loaded with the 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?

An output schema exists, so return values need no explanation, and the description covers purpose, safety, and timing for a parameterless tool. Only minor gaps remain around environment prerequisites or failure behavior when the vault path is invalid.

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 rubric the baseline is 4. There is nothing further the description could add on 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?

States a specific verb (initialize/repair) and resource (vault directory structure and default templates), so the agent knows exactly what the tool does. It doesn't explicitly contrast itself with any sibling, but no sibling in the list overlaps with this scaffolding function.

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

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

Gives a clear triggering context: 'Call this after cloning the repo or setting up on a new machine.' It does not name explicit exclusions or alternatives, but the when-to-use condition is unambiguous.

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 so well: it discloses that output is GENERATED prose, tagged type: synthesis, never re-extracted into the 正本, and saved outside 20-areas/research/. It also notes save writes to VAULT/20-areas/syntheses/ and that top_k is intentionally omitted so it tracks query_graph's default.

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 purpose and then structured into a workflow line plus a tidy Args block. The closing rationale about omitting top_k is useful but slightly tangential for a selector, keeping it just under maximum efficiency.

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 needn't be explained, and the description covers behavior, all parameters, and the retrieval-to-synthesis pipeline. 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 description coverage is 0%, yet the description documents every parameter: entity (comma-separated, auto-extraction capped at 3), fmt (listing the actual auto|mechanism|compare|list|methods options the schema does not enumerate), save (target directory), and model. This more than compensates for the empty schema.

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

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

States a specific verb+resource: answer a literature question as a fixed-format CITED synthesis note, with the retrieve→synthesize pipeline spelled out. It clearly distinguishes itself from retrieval-oriented siblings like query_graph by emphasizing synthesized prose rather than raw material.

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?

Explains the workflow (query_graph retrieval then Claude writes a cited summary) and notes the entity auto-extraction cap of 3 with a pointer to AGENTS.md's SOP. It implies when synthesis beats raw retrieval, but never states an explicit 'use query_graph directly instead when X' exclusion, so it stops short of full when/when-not 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 behavioral burden and does well: it discloses that raw_key is never stored (only its SHA-256 hash is persisted), that expires_days=0 means no expiry, and that role='member' requires user_uuid. It does not cover error behavior or permission failure modes, so it stops 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?

Front-loaded with the one-line purpose, then a compact per-parameter breakdown with no wasted prose. Slightly dense in the role/user_uuid explanation, but every line carries information the schema lacks.

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 elaboration, though the description still notes a plain-text summary. For a 6-parameter admin mutation tool with zero schema documentation and no annotations, the description supplies all the per-parameter and behavioral detail an agent needs.

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

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

Schema description coverage is 0% and all 6 parameters are undocumented in the schema, so the description must compensate — and it does, documenting action values, raw_key handling and lifetime, user_id meaning, role enums and defaults, member/user_uuid coupling, and expires_days 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?

States a specific verb (manage) and resource (API keys) plus the scope constraint (multi-user access, admin only). No sibling tool overlaps with key management, so an agent can select it unambiguously.

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 names the three actions and marks the tool admin-only, giving clear context for when it applies. It does not explicitly state when not to use it or point at an alternative, but no plausible sibling exists, 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 full burden. It does disclose a real behavioral trait beyond the name: the update touches frontmatter only ('without rewriting the whole file') and syncs to a DB, and it flags a proposed→accepted→superseded lifecycle. However it says nothing about permissions, reversibility, or what happens if the status is invalid.

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 summary, then a rationale sentence, then an Args block. Every element earns its place, though the multi-line status list is slightly verbose and could be tightened.

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, and the description covers the mutation, the DB sync side effect, and all valid status values. What is missing is failure/repair behavior and the note-type-to-status rules in fully explicit form.

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

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

Schema description coverage is 0% and no enums are declared, so the description is the only source of parameter meaning — and it delivers: it enumerates every legal status value grouped by note type, notes the repair-only values, and gives a concrete path format example. It compensates well for the empty schema.

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

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

Names a specific verb and resource ('Update the frontmatter status field of a note') plus the side effect ('sync to DB'). The clause 'without rewriting the whole file' implicitly carves it apart from the sibling update_note, though no sibling is named 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?

'Use this to track note lifecycle' gives a clear purpose context, and the status groupings map note types to the correct values (general/project notes vs decision/ADR notes). No explicit when-not-to-use or named alternatives, but the domain mapping is strong enough that an agent can pick the right status.

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

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

With no annotations, the description carries the full burden and does disclose substantial behavior: automatic project-slug routing into subfolders, the decision/adr and project special cases, and the fix- postmortem exception. It omits error handling, duplicate-title behavior, and permission requirements, but the key side-effect (where files land) is 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?

Front-loads the core purpose, then uses a structured block for routing rules and an Args section for parameters. The routing detail is dense but genuinely earns its place; length is justified by the complexity it resolves.

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. For a create/mutation tool with no annotations, the description covers the critical routing and per-parameter semantics; only edge cases such as collisions or permission failures are left unaddressed.

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: note_type enumerates the six valid types (absent from the schema), title notes kebab-case filename conversion, content is labeled optional post-template content, and tags specifies comma-separated format and frontmatter placement.

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 (create) and resource (note) plus scope (in the vault), and the routing rules make it clearly distinct from siblings like update_note, append_to_note, and read_note. An agent can tell what it produces without opening the schema.

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

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

Usage is implied by 'create a new note,' and the extensive routing rules describe how the tool behaves when invoked. However, it never states when to prefer this over alternatives (update_note, append_to_note) or any preconditions/exclusions, so guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses destructiveness, the guard condition that prevents deletion without a snapshot, and the safe dry_run default. It omits permission requirements, whether deletion is recoverable/rate-limited, and any logging behavior, so it is strong but not exhaustive.

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 dangerous operation and its safety condition, then the dry_run default, then the parameter notes — an efficient ordering. The Args block slightly duplicates the schema's defaults, which is mild redundancy rather than 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?

For a destructive, 2-parameter maintenance tool with no annotations, the description supplies the essentials: what gets deleted, what protects against mistakes, and the safe default. An output schema exists so return values need not be explained, but permission/irreversibility details remain unspecified.

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 schema entries carry only titles and defaults, so the description must compensate. It explains the meaning of both min_age_days (age threshold for candidacy) and dry_run (report-only vs. actually delete), which is exactly the semantics missing from the schema, though the stated defaults merely repeat the schema's default fields.

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

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

States a specific verb and resource ('Delete archived originals') plus the exact filter conditions (older than min_age_days, must have a snapshot), so the agent knows precisely what set of files is affected. No sibling tool (e.g. snapshot_note_tool) could be confused with this destructive maintenance operation.

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 operating context and a safety gate ('Safe to run: only deletes when a PNG snapshot exists') plus the dry_run default and how to activate real deletion. It stops short of naming alternatives or stating when *not* to prune (e.g. when snapshots are stale or storage is not a concern), which keeps it from 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?

No annotations exist, so the description carries the full burden. It does disclose the significant traits: admin-only access and that only write actions are recorded. It does not state read-only behavior, ordering, pagination beyond the limit parameter, or what happens on permission failure, so it falls short of the bar expected with zero annotation coverage.

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

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

Purpose and admin caveat are front-loaded in a single clear sentence, then parameters are listed compactly. No filler text, and it is not bloated for a three-parameter query 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 values need not be explained. For a simple filtered read tool with all-optional parameters, purpose, access requirement and filter semantics are covered; only richer filter-behavior and failure semantics are 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 one-line per-parameter notes are genuinely useful, clarifying the actor filter, tool filter and default limit. However they are thin for a 0%-coverage schema, offering no format hints (e.g. user_id shape, tool_name exact-match vs substring, limit bounds), so the description only partly compensates.

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

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

States a specific verb and resource: query the write-action audit log, and flags it as admin-only. Despite having 47 siblings, none is an audit-log reader, so it is easily distinguished from the notes, figures and sync tools around 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?

Usage is only implied by the resource name itself; the description never says when an agent should reach for the audit log versus, say, get_decisions or auth_context. The 'write-action' and 'admin only' qualifiers give some narrowing context, but no explicit when/when-not guidance is offered.

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 substantial work: it discloses that edges are aggregated ACROSS papers with verbatim evidence and source notes, that cross-paper agreement is surfaced as ×N, and that Path 2 is a recall fallback for missed relations. It omits auth requirements, rate limits, and result-size behavior, but the core behavioral model is well conveyed.

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, then organized into labeled Path 1 / Path 2 sections and an Args block, so an agent can scan it fast. Slightly more verbose than needed, and defaults are restated from the schema, but nothing is filler.

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

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

An output schema exists, so return-value shape needn't be re-explained, and the description covers both query paths plus all three parameters. It is complete enough to invoke correctly; the only shortfall is the absence of guidance on outcomes/limits that a no-annotation tool could have supplied.

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: entity is given with concrete examples ('TXNDC5', 'TGF-beta', 'pulmonary fibrosis'), mode is enumerated with a default despite the schema lacking enums, and top_k is described as 'snippet notes to pull for the recall net' with its default. Minor gap: top_k's effect on Path 1 output is unstated.

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 (knowledge-graph query for an entity) and decomposes it into two clearly named mechanisms: typed-edge retrieval with cross-paper aggregation and a verbatim snippet recall net. It also explicitly distinguishes Path 2 from the sibling search_snippets by noting it uses the 'same engine', so an agent can tell what this adds beyond that tool.

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 mode parameter is explained ('edges' | 'snippets' | 'both', default 'both'), which implies how to scope the query, and the recall-net rationale ('a relation the edge extractor missed is still surfaced') hints at when 'both' matters. However, there is no explicit when-to-use-this-vs-search_snippets guidance and no stated exclusions or prerequisites, leaving selection largely to inference.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the returned resolution (~768px long edge) and token cost (~256-400), and clarifies it returns a down-scaled thumbnail rather than the full-resolution image or whole page. It does not touch on permissions or whether the source note must already be indexed, but the cost/output disclosure is strong.

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 routing before the args, which is the right order. The 'Args:' block partly duplicates what could live in the schema, but the added example and cross-reference justify it; sizing is appropriate.

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 2-param read tool with no annotations and no output schema, the description covers purpose, selection criteria, both parameters, and the shape/cost of the return value. Only minor gaps (e.g., preconditions like an existing extracted figure) remain.

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: note_path is documented as a vault-relative path with a concrete example, and fig_index as a 0-based index cross-referenced to search_figures. This meaningfully exceeds a bare restatement of the param names.

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 ('Load ONE extracted figure as a down-scaled image') and situates it on a named 'recall ladder' between text search and full-page rendering. This lets an agent distinguish it from search_figures and read_note_as_image without opening either schema.

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

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

Explicitly states the condition that selects this tool ('Use this only when search_figures' text proxy ... can't answer the question') and names the alternative it is preferred over. Decision criteria are concrete rather than inferred.

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

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

No annotations exist, so the description carries the full burden. It adds the path-format context and implies a read-only fetch, but discloses nothing about behavior on a missing/invalid path, encoding of content, or size limits. For a simple read tool that is a modest but real gap.

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

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

Front-loaded single sentence with the purpose, followed by a compact parameter note. The 'Args:' block is slightly boilerplate for a one-parameter tool but does not pad the text meaningfully.

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. However, for a tool in a 45-sibling namespace, the description neither routes the agent away from search_notes/read_note_as_image nor covers failure modes, leaving the selection context thin.

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% — the only parameter is undocumented in the schema. The description compensates by defining the parameter as a path relative to vault root and giving a concrete example ('decisions/my-decision.md'), which is the key ambiguity an agent would otherwise hit.

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 (read) and resource (a specific note), plus the scoping key (relative path within the vault). It is clear, but it never distinguishes itself from nearby siblings such as search_notes (when the path is unknown) or read_note_as_image, 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 only implied: the mention of 'relative path' quietly signals that you must already know the path. There is no explicit when-to-use, no when-not-to-use, and no pointer to search_notes as the alternative when the path is unknown.

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 disclose that the tool returns a PNG directly to the calling agent's vision model, plus a text fallback. It still omits important behavior such as fallback triggers, permissions, and error handling, so it is only partially transparent.

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

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

The key purpose is front-loaded in the first sentence, and the second paragraph explains the efficiency rationale. The Args block is minimal and useful, though the rationale sentence is slightly promotional rather than strictly functional.

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?

The definition covers the basic output behavior and path semantics, which is useful given the lack of annotations and output schema. But it leaves out the fallback condition, exact return behavior in text mode, error cases, and how this tool relates to the read_note sibling, so it is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning for the single path parameter by specifying it is a relative path from the vault root, which goes beyond the schema's bare string type and title.

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 — reading a note as a PNG snapshot — and clarifies the output mode for VLM agents versus text fallback. It distinguishes the tool from a plain text note reader implicitly, but does not explicitly name the sibling read_note as the alternative.

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

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

The description gives implied usage context by calling out VLM agents and noting the direct-image path is cheaper and faster than an intermediary. However, it does not state when to use this versus read_note, nor when the text fallback applies or when not to use this tool.

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 substantial work: it enumerates the three deterministic resolution strategies, promises no Vision-model calls, states ambiguous cases are deferred, and guarantees Research Markdown is never modified. It does not describe how index rows are mutated or whether changes are reversible, so it falls 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?

Purpose is front-loaded, followed by scope rules and then a clean Args block. Every section earns its place, though the evidence list and the args list could be marginally tightened.

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 scope, deterministic behavior, and all params. For a moderate-complexity tool with no annotations, it is largely complete, missing only detail on how index rows are written.

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 documents all three params: note_paths (vault-relative Markdown paths, max 20), dry_run (report without downloading/updating), limit (1-20). The behavioral meaning of dry_run and the path semantics are genuinely additive, though it adds little beyond the schema's constraints.

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 (reconcile) and resource (figure files and index rows), then narrows it with 'without Vision-model calls,' which distinguishes it from vision-based siblings like extract_figures_for and read_figure. An agent can tell what this does and roughly where it sits relative to figure-handling tools.

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

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

The phrase 'without Vision-model calls' and 'Ambiguous cases remain in the manual queue' imply a deterministic-only lane, but no sibling is named and there is no explicit 'use this instead of X when Y'. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does so well: it discloses fail-closed all-or-nothing semantics, byte-for-byte verification before any write, an explicit guarantee that Markdown and figure DB rows are untouched, and that dry_run defaults to true. It omits permission/auth requirements and rollback behavior on mid-batch failure, keeping it below 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?

The core semantics (fail-closed, no side effects) are front-loaded in two tight sentences, followed by a compact Args block that earns its space given 0% schema coverage. The prose is slightly longer than strictly necessary, preventing a 5.

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

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

For a no-annotation write tool with an output schema, the definition covers failure semantics, side-effect guarantees, limits/defaults, and the fallback path. Return-value details are rightly omitted since an output schema exists. Only auth/permission and partial-failure recovery details are 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 documents all five parameters with real semantics: the ≤20 cap on note_paths, the 1–20 ranges for both limits, dry_run's validate-without-writing meaning, and that source_pdfs must align positionally with note_paths and is only for a verified copy. Only minor gaps remain (e.g. behavior if source_pdfs length mismatches note_paths).

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

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

The opening sentence gives a specific verb+resource ('Restore missing legacy embedded-image files from their original PDFs') and immediately scopes it to legacy PDF-sourced images, which is enough to separate it from generic figure tools. It does not explicitly distinguish itself from near-neighbors like reconcile_figures, 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 context is implied by the fail-closed explanation and the dry_run default, telling the agent this is a validate-then-write workflow. However, it never states when to prefer this over reconcile_figures or backfill_figure_text, nor any preconditions for invoking it, so the when-to-use guidance is only inferred.

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 disclose one behavioral trait beyond the schema: only authors, author_ids, DOI/PMID/PMCID, journal, publication_year and canonical_url are written from metadata. But it omits key write behaviors such as overwrite/duplicate handling when a note already exists, network/auth requirements for fetching URLs or PDFs, and rate 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?

Front-loaded with the core action in the first sentence, then an Args block that is dense but earns its place; the folder/format guidance is useful rather than filler. Slightly verbose in places but no wasted sentences.

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 parameter documentation is thorough with examples and folder/naming conventions. The remaining gap is the absence of write-collision or duplicate-handling semantics for a tool that saves into a vault.

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: all six parameters are documented with defaults, accepted values, and a concrete format example ('2024_Bakr_ARID1A'). It even constrains the nested metadata object's writable fields, which the schema leaves fully open.

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 chain (convert a web article or PDF into a markdown note) plus the terminal action (save it to the vault). This clearly distinguishes it from siblings like new_note (blank note creation) and search_articles (retrieval).

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 concrete context cues, e.g. use '20-areas/research' for academic papers with DOI/journal and the 'YYYY_Author_ShortTitle' naming convention for research. However, it never names an alternative tool or states when NOT to use this (e.g. vs new_note/append_to_note).

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

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

Annotations already cover the safety profile, and the description adds meaningful behavior: author matching uses only article frontmatter, supports full names, surname-first initials and ORCID, and flags surname-only results as ambiguous. This is useful context beyond structured fields, though it says nothing about rate limits or result ordering.

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

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

Four tight sentences, front-loaded with purpose and followed by routing guidance and the key caveat. No filler, though the phrasing 'article-only structured bibliography fields' is slightly jargon-heavy.

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. However, with seven parameters and 0% schema coverage, the description leaves most input semantics unexplained, making it only adequately complete for a multi-field search tool.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the burden. It only explains the author parameter's accepted formats and leaves doi, pmid, pmcid, year, title, and limit undocumented, adding little 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 ('Search article-only structured bibliography fields') and explicitly differentiates from the sibling search_notes. An agent can tell this is the bibliography-focused search tool without opening the schema.

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

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

Explicitly says to use this instead of search_notes when asking for papers by an author, giving a clear alternative and selecting condition. It does not cover when to use it for non-author fields like DOI or year, so it falls short of full when/when-not 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 does disclose two search modalities (OCR vs semantic), which is genuinely useful behavioral context. It says nothing about result limits, ranking, permissions, or that the operation is read-only, so key operational traits remain 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?

The purpose sentence is front-loaded and the args block is compact. The 'Args:' formatting is slightly redundant with the schema, but the example values earn their 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 values need not be explained, and with a single parameter the description covers the calling surface adequately. What is missing is only the routing distinction between this tool and the other search_* 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% and there is a single required parameter, so the description must carry the load; it does so with concrete example values ('UMAP', 'TYRP1', 'cluster', 'p < 0.001'). It still doesn't say how a query is routed between OCR and semantic matching, which is the one semantic detail an agent would want.

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 ('Search figures') plus the corpus scope ('across all saved articles') and two matching modes (OCR text, semantic description). It does not, however, distinguish itself from near siblings such as search_snippets, search_articles, or read_figure, so an agent must infer the boundary itself.

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 only implied by the scope phrase 'across all saved articles'; there is no explicit when-to-use guidance or statement of when to prefer read_figure/annotate_figure or the other search_* tools. The agent can guess the intent but receives no routing rules.

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 so well: it discloses the archival exclusion, the 7-day news window, the two-group return shape, and the Markdown output format. It omits pagination/rate behavior, but for a read-only search that is a minor gap.

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

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

Front-loaded purpose followed by scannable group bullets, then compact Args/Returns. Slightly padded by the two-paragraph use-case block, but every section 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?

Low complexity, one required param, output schema present (so return values need not be spelled out — though it does anyway). The description covers scope, freshness, and grouping; only failure/empty-result behavior is left unstated.

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 largely does: it gives a query example and clarifies that limit means 'max results per group' with a default of 10 — a per-group semantic the schema alone does not convey.

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 ('hybrid search') and explains exactly what the two result groups contain, including the exclusion rule (knowledge excludes cnyes_archive) and the news freshness window. It effectively implies the distinction from search_notes and search_news_tool by describing itself as a combined call, but 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?

Gives concrete use-case context ('finance research... general knowledge work') that tells the agent when this combined query is the better pick. It does not state when NOT to use it (e.g. when a single-group search is sufficient), so it stops short of full 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?

No annotations are provided, so the description carries the disclosure burden. It discloses the scoping constraint ('Only searches cnyes_archive notes within the last N days'), which is useful behavioral context, but says nothing about ordering, result limits, or rate behavior. An output schema exists so return shape need not be described here.

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 scope and the routing sentence, then the args. The Args block largely restates the schema, which is mildly redundant, but overall it is compact and each sentence earns its place.

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

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

For a two-parameter read-only search tool with an output schema, the description covers purpose, scope, and both parameters adequately. The main omission is disambiguation from the other search-related siblings, but the critical information for correct invocation is 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: query is explained as a stock ticker, keyword, or company name with concrete examples, and days is described as the lookback window with its default. This meaningfully exceeds the bare schema titles.

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

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

States a specific verb (search) and resource (recent cnyes daily news archives), and explicitly scopes it to cnyes_archive notes. It names the sibling it is not (search_notes) so an agent can distinguish it from the knowledge-base search without opening either schema.

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

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

Explicitly routes the agent: 'Use search_notes for knowledge base search,' giving a clear when-not condition and alternative. It does not differentiate against the other search siblings (search_articles, search_snippets, search_grouped), so it falls short of a full 5, but the primary alternative is 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?

No annotations are provided, so the description carries the full burden, and it does well: it discloses the retrieval stack (BM25 + cosine, bge-m3 1024d) and the graceful degradation chain (embedding server -> BM25-only -> file scan). It omits operational traits like latency, result limits, or guarantee of ordering, but the fallback behavior is exactly the kind of non-obvious context an agent needs.

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

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

The scope constraint leads, the routing hint follows, then the mechanics. Every sentence earns its place and there is no padding despite covering three distinct topics.

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 parameter plus fallback behavior are covered. The only gap is the absence of guidance relative to the broader set of search_* siblings, which for a 48-tool namespace matters somewhat.

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% on a single required parameter, so the description must compensate and does: it tells the agent the query accepts both natural language and keywords, which materially affects how the query string should be formed. Given only one simple parameter, this is adequate compensation.

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

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

States a specific verb (hybrid semantic + full-text search) over a specific resource (knowledge notes) and explicitly scopes out daily news archives. The sibling search_news_tool is named, so an agent can route between the two without opening a schema.

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

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

Explicitly routes news queries to search_news_tool, which is the key disambiguation in this sibling cluster. It does not, however, distinguish itself from other retrieval siblings such as search_articles, search_snippets, find_related_notes, or search_grouped, so usage is clear but not fully delimited.

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, so the description carries the behavioral burden. It usefully guarantees output is verbatim and never rewritten and includes a citation, but says nothing about permissions, scope, or limits. Since an output schema exists, the return-shape burden is lighter.

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, and the Args block cleanly follows. Slightly emphatic with capitalized VERBATIM and dash clauses, but each sentence carries useful content.

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-param search tool with an output schema, the description covers purpose, use cases, and both parameters adequately. The only real gap is not positioning itself against sibling search 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 coverage is 0%, so the description must compensate, and it does: it explains query as a keyword/phrase with concrete examples ('TGF-beta fibrosis') and top_k as the count of notes to pull from, with the default. Both parameters get meaning beyond the bare schema titles.

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: 'return the VERBATIM source sentence from each of the most relevant notes, with its citation.' This distinguishes it in substance from a whole-note reader, but it never names the obvious sibling (search_notes) to anchor the distinction.

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

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

Gives positive use cases ('what does the literature say about X', 'a factor's role'), which implies context. But with many search siblings (search_notes, search_articles, search_figures, search_grouped) it never says when to prefer this over them, so routing is left to inference.

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

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

With no annotations, the description carries the full burden, and it does disclose one meaningful trait: the operation is non-compressing (non-mutating, safe to call for inspection). It says nothing about permissions, cost, or side effects, and the output schema covers return values.

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

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

A single tight sentence with the action front-loaded and no filler; every clause adds 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 zero-parameter status tool with an output schema, the description adequately covers what it reports (current triggers, candidate list) and that it is non-compressing. The only gap is that the 'sleep' domain concept is never grounded.

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 rule a 4 applies; there are no inputs whose semantics could be clarified further.

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 (check) and resource (sleep triggers) plus a secondary action (list candidates). The phrase 'without compressing' implicitly distinguishes it from vault_sleep/consolidate_tool, giving partial sibling differentiation, though the domain term 'sleep' remains opaque without external knowledge.

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

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

No explicit when-to-use or when-not-to-use statement. The contrast with the destructive/compressing operations is only implied by 'without compressing', leaving the agent to infer that this is the inspection step before invoking vault_sleep.

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 must carry the full behavioral burden. It reveals that snapshots scale token cost by tier (400/256/100 tokens), which is genuinely useful. But it omits whether the render is cached, whether it overwrites existing snapshots, permission requirements, error conditions, or side effects. Without annotations and with an output schema present, more transparency is needed.

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; parameter documentation is compact and structured. The Args section is typical of docstring-style rendering and earns its place. Slightly verbose formatting but no wasted sentences.

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-parameter tool with an output schema, the return format needn't be described. The description covers purpose and parameters but leaves behavioral traits (caching, overwrite, permissions) and usage context unaddressed. It's minimally viable but not complete.

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

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

Schema coverage is 0%, so the description must compensate. It documents note_path with a format example and lists all three tier enum values with their token counts. This is substantial added value beyond the bare schema, though the tier parameter could note what happens if omitted (schema default 'base' fills that 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 clear verb+resource: 'Render a markdown note to PNG snapshot.' This distinguishes it from read_note, new_note, and other note tools by specifying the PNG conversion. However, it doesn't explicitly differentiate from read_note_as_image, a nearby sibling that also produces images from notes.

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 explains 'for token-efficient storage' which hints at a use case, but provides no explicit when-to-use or when-not-to-use guidance. An agent cannot tell from the description alone when this tool is preferable to read_note_as_image or other note-reading alternatives.

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 and a mutating backfill operation, the description discloses real behavioral traits: each call is a bounded unit of work, the response reports how many notes remain, and the loop-until-zero pattern prevents long blocks. It does not state permissions, idempotency, or failure behavior, and it outsources detail to 'docstring' references an agent cannot read.

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

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

The primary purpose and the limit semantics are front-loaded and clear, but the parenthetical digressions about architecture debt and a fixed date (2026-09-04), plus two pointers to internal docstrings, do not help an agent decide or invoke anything.

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 describing the return payload is unnecessary, and the description still usefully notes that the response carries a 'remaining' count to drive looping. For a one-parameter tool with no annotations, the main residual gap is mutation safety/permission context.

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

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

Schema coverage is 0%, so the description must carry the single parameter, and it does: 'max notes to process this call (default 200)' plus the interaction with repeated calls. It adds meaning beyond the bare integer/default in the schema, though it gives no guidance on choosing a smaller or larger limit.

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 ('backfill note_chunks for notes whose chunks are missing or stale') and explicitly positions itself against sibling sync_index, whose own backfill is described as capped small. An agent can distinguish the two without opening either schema.

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

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

Explicitly names the condition for use ('draining a large backlog') and rules out the alternative ('sync_index()'s own chunk backfill is capped small so it stays fast'). It also gives the invocation protocol: call repeatedly until 'remaining' reaches 0.

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 real behavioral traits: a bounded chunk-backfill cap (_SYNC_INDEX_CHUNK_LIMIT), the deliberate refusal to drain the whole backlog in one call, and the rebuild-via-scan behavior. It stops short of stating whether the rebuild replaces or preserves existing index state and what the cost/runtime profile looks like.

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 sentence one, then the when-to-run conditions, then the edge-case escape hatch. Every sentence carries distinct information with no redundancy.

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

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

An output schema exists, so return values need no explanation, and the description covers triggers and the backlog-limit caveat. The one gap is the mutational effect on the existing index (rebuild vs. merge), which matters for a 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate (baseline 4). The mention of _SYNC_INDEX_CHUNK_LIMIT is an internal constant, not an argument, so no parameter semantics are needed.

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

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

States a specific verb ('Rebuild') and resource ('the DuckDB index by scanning all vault markdown files'), making the operation unambiguous. It is distinguishable from siblings like sync_notes and sync_chunks_tool by naming exactly what gets rebuilt and the secondary chunk backfill.

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 trigger conditions ('after adding notes manually, or when setting up on a new machine') and routes the agent to an alternative ('run sync_chunks_tool() separately to drain the rest') when the outstanding backlog exceeds the internal limit.

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, and it discloses only scoping (requested notes only). It says nothing about whether the operation is idempotent, whether it mutates or overwrites note content, what happens to notes not listed, or cost/latency of reindexing.

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

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

A single front-loaded sentence with no filler, and the scoping constraint ('only the explicitly requested') lands before anything else. It is terse to the point of under-specification rather than 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?

An output schema exists so return values need not be described, but for a mutating reindex operation with no annotations and an undocumented parameter, the description is too thin. An agent cannot determine path format, side effects, or how this differs from the several other sync/index tools in the sibling list.

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% for the single required parameter note_paths, so the description must compensate and does not. It gives no hint about path format (vault-relative vs absolute), whether extensions are required, or whether the array has practical limits.

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 (reindex) and resource (vault notes), with the scope qualifier 'only the explicitly requested' that distinguishes it from a full-vault sync. It does not name its closest siblings (sync_index, sync_chunks_tool), so differentiation is inferred rather than explicit.

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

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

The phrase 'only the explicitly requested' implies this is for targeted reindexing rather than a bulk operation, which is useful implied guidance. However, it never states when to choose this over sync_index or sync_chunks_tool, nor any prerequisite such as notes needing to already exist.

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 the ranking formula (access_count / time_decay), the default mode, and that it is a read operation via 'Return'. It does not address pagination or whether the ranking is computed live, but the algorithmic disclosure is above the norm.

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 purpose and well-sectioned. The Args and Returns blocks largely restate the input and output schemas, which is mild redundancy, but the mode explanations earn their space.

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-parameter read tool with an output schema already covering the return format, the description supplies everything else needed: purpose, ranking semantics, mode selection, and use cases. Nothing required for correct invocation is missing.

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

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

Schema coverage is 0%, so the description must compensate and does: it defines 'by' with both valid values and the default, defines 'limit' with its default, and adds meaning beyond the schema by explaining what the 'score' value actually represents (Ebbinghaus decay).

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 with scope: 'Return your most important notes ranked by engagement.' The ranking dimension (engagement-based top-N) clearly differentiates it from siblings like search_notes, find_related_notes, and read_note, which retrieve rather than rank.

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?

Explains both ranking modes with explicit 'Best for' conditions (score for core knowledge nodes/most-researched stocks, recency for resuming recent work) plus three concrete use cases. The agent knows exactly which mode to pick and for what scenario.

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 the destructive semantic ("Replace the contents" = overwrite, not append), which is meaningful for a mutation tool. However, it omits permissions required, whether the file is created if absent, and whether the prior content is recoverable.

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 primary action and resource in one sentence, followed by a compact Args block. Efficient overall, though the docstring-style Args formatting is partly boilerplate that the schema already conveys.

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. For a single-parameter destructive tool with no annotations, the description is adequate but thin – it should say what happens on overwrite (creation if missing, loss of prior content) to be fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does add real meaning: the parameter is the FULL content (not a diff/patch), and the expected format is markdown. This is enough to call the tool correctly, though it does not describe edge cases like empty input.

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

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

The description names a specific verb ("Replace") and a precise resource ("the contents of memory/goals.md"), so the agent knows exactly what file is affected. It does not differentiate from siblings, but no sibling touches goals.md, so the lack of differentiation is not a real gap.

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

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

No when-to-use guidance, no prerequisites, and no alternatives are mentioned. The 'Replace' wording hints at a full-overwrite scenario versus tools like append_to_note, but the description never states the condition that selects this tool or warns against using it for partial edits.

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 must carry the full safety burden. It discloses the write operation, the target field (`related`), the semantic model (bge-m3, 1024d), and that it only touches notes with embeddings. It does not say whether existing/manual related entries are overwritten, whether the change is reversible, or what permissions are needed – meaningful 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?

Front-loads the action, then the mechanism, then a clean Args block. No redundant sentences; every line contributes scope or behavior information.

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

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

An output schema exists, so return values need not be explained, and a single optional parameter keeps the surface small. The description covers purpose, mechanism, and scope adequately; the only real gap is the overwrite/reversibility behavior, which is compounded by absent 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 fully compensates: it defines note_path as a relative path within the vault, gives a concrete example ('decisions/my-note.md'), and explains the empty-string default selects all notes. This is the one parameter and it is well 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: refresh related wikilinks in one or all notes, and specifies it writes to the frontmatter `related` field. This distinguishes it from the read-oriented sibling find_related_notes, though it never names that sibling to make the split explicit.

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 implicit scoping guidance via 'one note or all notes' and 'Leave empty to update ALL notes that have embeddings', which tells the agent how to control scope. However, it never states when to prefer this over find_related_notes, update_note, or the other link/graph tools, so alternatives are left to inference.

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

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

No annotations are provided, so the description carries the full burden. It clearly discloses the destructive overwrite behavior and even the exact parameter semantics, but it does not mention permissions, whether backups occur, or the return format. A 4 reflects strong disclosure of the core destructive trait with minor gaps.

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

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

Two sentences of prose plus a focused Args section. The destructive nature is front-loaded, and every line serves a purpose without redundancy.

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

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

For a two-parameter, destructive write tool with no annotations but an existing output schema, the description covers the operation, the destructive semantics, parameter usage, and the alternative tool. Nothing essential is missing for correct agent 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 provides an example for path ('decisions/my-decision.md') and explicitly states that content replaces the entire file, which is critical for correct invocation. This fully compensates for the absent schema descriptions.

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

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

The description states a specific verb (overwrite) and resource (note), and immediately differentiates from the sibling append_to_note by naming the destructive vs. additive behavior. An agent can distinguish update_note from append_to_note without inspecting schemas.

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

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

Explicitly states when to use (rewriting or restructuring) and when not to (adding content without losing existing text), naming the alternative (append_to_note). This is textbook when/when-not/alternative guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that operation is gated by a config file, that recent/high-Ebbinghaus notes are skipped, and that dry_run previews rather than mutates. It does not say whether compression is reversible, what 'compress' does to note content, or whether the operation requires specific vault permissions.

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 in one sentence, then lists the threshold configuration and skip rule compactly, then the single argument. Slightly over-structured ('Args:' heading for one parameter) but free of 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?

An output schema exists, so return values need not be described. For a mutating vault operation with no annotations, the description covers trigger conditions, config source, skip logic, and a preview mode – the main residual gap is whether compression is destructive or recoverable.

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: 'If True, show candidates without making changes' tells the agent exactly what dry_run does, which the bare boolean-with-default schema does not. With only one parameter, this is adequate, though the default behavior when omitted is only implied by the schema's default:false.

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 ('Compress old low-activity notes to slim down the vault') with a clear scope: old, low-activity notes. It does not explicitly distinguish itself from near-siblings like consolidate_tool, prune_archive_tool, or sleep_status, so an agent must infer the boundary from the names alone.

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

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

The description explains which notes qualify (per-folder age thresholds and Ebbinghaus score <= 0.5), which is effectively usage criteria. However, it never says when to prefer this tool over prune_archive_tool, consolidate_tool, or sleep_status, nor whether a prior audit or dry_run pass is recommended. Usage is implied rather than directed.

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