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

With no annotations, the description must carry the behavioral burden. It usefully discloses that this is a state-gating mutation that unlocks execution and that it returns a plan summary, but says nothing about permission requirements, whether approval can be revoked, or what happens when no pending plan exists.

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

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

Three short sentences, front-loaded with the action and its effect, followed by prerequisites and return value. Every sentence carries information an agent needs to call this correctly.

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 zero parameters, no annotations, and no output schema, the description covers the essentials: what it does, when it must be called relative to siblings, and roughly what it returns. The main residual gap is error/precondition behavior when no plan is pending.

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

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

The tool takes zero parameters, so there is no parameter semantics to clarify; the baseline for a 0-param tool applies. Nothing in the description misleads about inputs.

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 pairs a specific verb (approve) with a specific resource (the pending inbox plan) and states the effect ('to enable execution'). It is mostly distinguishable from siblings, though it does not directly contrast with get_inbox_plan, which presumably supplies the plan being approved.

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

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

It gives explicit ordering constraints naming the exact sibling calls: after scan_inbox() and before execute_inbox_file_batch() or get_inbox_content_batch(). An agent can place this call in the workflow with no inference required.

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. It does useful work by disclosing the return payload and the interaction contract with write_vault (self-check plus refusal on hit), which is genuine context beyond structured fields. However, it is silent on what 'similar' means — no match threshold, no case sensitivity, no scoping to vault root, no indication that the call is side-effect free — so an agent cannot predict a false negative or understand the cost of a call.

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

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

Front-loaded with purpose, then return shape, then the when-to-use caveat — a sensible order with no filler sentences. Every line earns its place, though the guidance sentence runs long and could be split for faster scanning.

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?

Return shape is covered despite there being no output schema, and the write_vault interaction is explained, which covers the biggest unknowns. The remaining gap is parameter behavior: for a three-parameter, zero-coverage schema this description should say what each argument means and how matching is scoped.

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 all three parameters are undocumented, yet the description never mentions any of them. It doesn't clarify what values `type` accepts, how `title` matching behaves, or what the optional `url` contributes to the similarity decision, so an agent must guess the semantics that drive the whole result.

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

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

States a specific verb and resource: check whether a similar vault item already exists, and the following sentence pins down the exact return shape. It implicitly distinguishes itself from near-siblings like find_nodes and search_vault by framing the tool as a dedup decision, but it never names those siblings explicitly, so the differentiation is inferred rather than stated.

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?

Unusually strong routing guidance: it says write_vault already runs this check and refuses on a hit, so a separate call is only needed to look before building the node. It gives a concrete motivating scenario (deciding between a new save and an update before drafting content), covering both when to call and when not to.

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 at all, the description carries the full burden and does so: it discloses the file written, that an existing user relation may be mutated to back-reference this one, that unknown inverse_of yields a warning rather than an error, and that warnings are returned in both success and failure payloads. It also documents both return shapes, so the agent knows exactly how validation failure surfaces.

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

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

Front-loaded with the action and file, then return shapes, then enforcement rules, then argument semantics — a logical escalation. The return-shape lines are justified because no output schema exists, but the block is dense enough that the ordering between rules and args could blur on a quick read.

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

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

For a five-parameter mutation with no annotations and no output schema, the definition covers the write target, validation gates, cross-relation side effects, warning-versus-error distinction, and both response shapes. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema description coverage is 0%, so the description must compensate and it does: each of the five parameters gets meaning beyond the schema — name must be lowercase and hyphenated, description should encode directionality, group examples are given, inverse_of's resolution behavior is explained, and symmetric is defined in semantic terms. This is more than the schema's bare 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 and resource ("Define a new user relation") plus the exact persistence target (relation-dictionary-user.yaml), which separates it from the sibling define_type. It never explicitly names define_type or validate_type as the alternative, so the sibling differentiation is inferable rather than stated.

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 preconditions: the name must not collide with canonical or existing user relations, every relation needs an inverse or must be symmetric, and symmetric cannot be combined with inverse_of. The lint_vault reference hints at the downstream validation workflow, but there is no explicit statement of when to call define_relation versus define_type or validate_type.

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 names the target file (ontology-user.yaml), states the success and failure return shapes including an `errors` array, and enumerates validation invariants checked before writing. It stops short of saying whether an existing definition is overwritten or whether a vault root must be set first.

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, then return contract, then rules, then args — a sensible order with little waste. The rules and args sections partially restate each other (e.g. the `extends` constraint appears in both), costing a bit of length.

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

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

No output schema exists, but the description supplies both success and failure return shapes, cutting rules, and per-parameter constraints — enough to call it correctly. Missing only write semantics on re-definition (overwrite vs error) and any prerequisite about the vault root.

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: name (lowercase, hyphenated), extends (canonical root only, not a user type, not `skill`), description, and fields with the `values?` rule for enums plus the allowed type set. That is materially more than the bare schema types 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 and resource — "Define a new user type and append it to ontology-user.yaml" — and names the exact artifact mutated. An agent can distinguish it from `validate_type` (checks) and `define_relation` (relations) 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?

Usage is implied by the enumerated pre-write rules, which tell the agent what will be rejected, but there is no explicit when-to-use or when-not-to-use guidance. It never points at the obvious alternative `validate_type` as a pre-check, even though it is the natural sibling for that purpose.

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 supplied, the description carries the full burden and does disclose the two most important traits: the operation is irreversible and requires user confirmation. It does not cover secondary behavior such as what happens to inbound links/references or whether a missing path errors or no-ops.

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 destructive action and its permanence are front-loaded in the first sentence, the parameter forms follow, and the safety warning closes. No sentence is redundant.

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

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

For a single-parameter destructive tool with no annotations and no output schema, the description covers the essentials: what it destroys, that it cannot be undone, that confirmation is required, and how to address the target. Only edge-case behavior (missing path, dangling references) is 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 does: it enumerates the three accepted path forms (8-character hex UID, absolute path, path relative to vault_root) and gives a concrete example. It omits failure behavior for an unresolvable path, keeping it just short of full coverage.

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 a vault item') and adds the crucial qualifier 'permanently', which separates it from restore_vault and undo_last_vault_change in the sibling set. It stops short of naming those alternatives explicitly, so it is clear but not fully differentiated.

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

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

Provides a strong procedural precondition ('Always confirm with the user before calling this'), which is real usage guidance. However, it never says when to prefer this over siblings like patch_vault, restore_vault, or undo_last_vault_change, so routing between tools 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 provided, the description carries the burden and does reasonably well: it declares the read-only nature via 'Show', explains the unified diff convention ('-' removed, '+' added), and discloses the return shape as {diff} or {error}. It stops short of describing failure conditions (e.g., invalid commit hash, missing path or binary/large diffs), which would have made this a 5 for an unannotated 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?

Three short sentences, front-loaded with purpose, then the diff-reading convention, then the prerequisite and return shape. Every sentence carries information the agent needs, with no filler or repetition of the tool name.

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 no annotations and no output schema, the description covers purpose, workflow prerequisite, output format convention, and return shape ({diff} or {error}). The remaining gap is the exact expected form of the 'path' argument and error conditions, which is minor but non-trivial.

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 both parameters rely on the description. The description does add meaning for 'commit' by calling it a commit hash sourced from history_vault, and 'path' is implied to be the node path by 'change one commit made to a node'. However, it never states the expected format of 'path' (vault-relative? node ID?), leaving half the parameter semantics to inference.

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

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

The description opens with a specific verb and resource: 'Show the change one commit made to a node', which is clearly distinct from list/history style siblings. The phrase 'as a unified diff' further defines the output form. What keeps it from a 5 is that it doesn't explicitly contrast itself with siblings like read_vault or history_vault, though it does route the agent to history_vault for the commit hash.

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 a concrete workflow prerequisite – 'Get the commit hash from history_vault' – which tells the agent how to obtain the required input before calling. It does not state when to prefer this over read_vault or history_vault, and gives no exclusion conditions, so it's clear context without full 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 the destructive step (staging file deleted on success, kept on duplicate), the duplicate-parking semantics, plan lifecycle effects, and partial-failure reporting via `failed`. What it omits is permissions/auth requirements and whether a partially failed batch leaves the plan in a recoverable state.

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

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

It is front-loaded with the action, then the per-item behavior, then the exception path, then the return shape. Every sentence carries distinct information, and no line restates the name or pads with 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?

There is no output schema, and the description compensates by spelling out the exact return object including the `duplicates` and `remaining` fields. Combined with the approval prerequisite and the duplicate-resolution path, an agent has everything needed to call it and interpret results.

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

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

The tool takes no parameters, so the baseline is 4. The description still adds useful context by revealing that batch size comes from configuration (budget_per_run.files), which the empty schema would 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?

The description opens with a specific verb and resource ('Execute the next batch of file-category items from the approved plan') and scopes it to file items, which implicitly separates it from the content-oriented siblings get_inbox_content_batch and get_inbox_plan. An agent can identify what it does without opening a schema (there are no parameters).

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

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

It states a hard prerequisite ('Plan must be approved before calling') and names the follow-up tool and exact status values needed to resolve duplicates, which is strong routing guidance. It does not explicitly say when to prefer a content batch instead, so the file-vs-content exclusion is only 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?

With no annotations, the description carries the full disclosure burden; it usefully signals this is a lightweight network call whose payload omits page body content. It says nothing about failure modes (non-HTML pages, unreachable URLs, timeouts), truncation, or whether results are cached, which matters for a network-dependent 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?

Three short sentences, front-loaded with the capability, then scope, then the alternative. No filler and nothing redundant.

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

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

For a simple one-parameter read tool with no output schema, the description usefully enumerates the returned fields and warns about the missing page body. Only network-failure behavior is left uncovered, which is a minor gap at this complexity.

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?

Only one parameter, and schema description coverage is 0%, so the description must compensate. It implies a URL to fetch but adds no format guidance (absolute vs. relative, scheme requirements) or what happens with redirects, so meaning beyond the bare schema field is minimal.

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 ("fetch a URL") plus the exact outputs (title, site name, description), and explicitly bounds the scope with "does not return full page content." That is enough for an agent to distinguish it from content-extraction siblings without opening the schema.

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

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

Gives an explicit use case ("for bookmark saves") and an explicit when-not with a named alternative ("use the article type instead"). The only weakness is that "the article type" does not map to any sibling tool name, so the agent must guess which tool actually performs full extraction.

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

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

With no annotations, the description carries the full behavioral burden and does disclose meaningful traits: the default state='active' excludes archived nodes, state=None returns all, has_asset_scheme matching is case-insensitive, and dates are ISO YYYY-MM-DD. It omits result limits/pagination, ordering, and whether there is a cap on matches, so an agent cannot predict behavior on large result sets.

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?

Well front-loaded: a summary sentence, the returned entry shape, then an Args block ordered by parameter. The subtype line is long and multi-line, but its enumeration is genuinely informative rather than filler, so little needs trimming.

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 13-parameter filter tool, all parameters are explained, defaults are clarified, and the default archived-exclusion behavior — the most likely source of wrong results — is called out. Remaining gaps are ordering/limit behavior and how it differs from sibling query tools; the return-value explanation is a bonus given an output schema already exists.

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

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

Schema description coverage is 0% across 13 parameters, so the description does all the work — and it documents every parameter with real semantics: comparison directions (due_before means due_date <=, due_after means >=), enum-ish subtype vocabularies per node type, and the has_asset vs has_asset_scheme distinction. This is exactly the compensation a low-coverage schema requires.

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 vault nodes matching any combination of filters,' plus a concrete result shape ({uid, title, type, subtype, path, state, status, due_date, language}). It does not name or contrast itself with likely siblings such as search_vault, query_recent, list_vault, or query_neighbors, so the agent must infer the boundary between structured filtering and text search.

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: 'matching any combination of filters. At least one should be provided' sets a precondition that at least one filter is needed, which is useful. But there is no guidance on when to prefer this over search_vault (free text), query_recent (recency), or query_neighbors (graph traversal), and no statement about what happens if no filter is supplied.

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. "Find" and "Returns a list" imply a read-only operation, and the return shape is disclosed, but nothing confirms non-mutation, whether the scan is recursive through subdirectories, or whether an empty result vs. missing assets/ directory is possible. Useful but incomplete behavioral picture for a scan 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?

Three short, front-loaded lines: what it finds, what it returns, when to use it. The return-value sentence is somewhat redundant because an output schema exists, but it is brief and sets expectation cheaply.

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, output-schema-backed read tool, the description covers purpose, scope, and usage. The only meaningful gap is the lack of confirmation that it is read-only and non-recursive vs. recursive, which matters for an asset-scanning sibling set.

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, so the baseline of 4 applies. The description correctly adds no parameter discussion and instead spends its words on scope and return shape.

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?

Specific verb and resource with an explicit scope constraint ("files in assets/ that have no registry entry"), and it names save_asset as the downstream tool whose output it differs from. An agent can distinguish this from siblings like scan_directory or lint_vault 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?

It states the situation that calls for it ("surface ghost files that were dropped into assets/ without going through save_asset"), which is clear usage context. It does not name alternatives such as scan_directory, resolve_asset, or lint_vault, nor any exclusion, 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 supplied, so the description carries the full behavioral burden. It discloses randomness and the output format, but says nothing about uniqueness guarantees, collision risk, or whether the call has any side effects on the vault, which matters for a tool whose name suggests state creation.

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, front-loaded with the verb and the precise output spec, with zero filler. Nothing could be removed without losing 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 the description need not explain the return value, and the zero-parameter schema is trivially simple. The only shortfall is the absence of any note on uniqueness or side-effect freedom, which is minor for a generator but would be the last thing needed for full completeness.

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 and the input schema is an empty object, so there is nothing for the description to disambiguate. Baseline of 4 applies; the sentence correctly implies no input 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?

The description gives a specific verb (generate) and resource (UID) plus the exact output shape: a random 8-character hex string. No sibling tool produces identifiers, so an agent can distinguish this from write_vault, define_type, or the query tools without opening any schema.

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

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

The phrase 'for a new vault item' implies the calling context but never states explicit when-to-use or when-not-to-use conditions, nor does it name an alternative approach. For a zero-argument utility the risk is low, so implied usage is adequate rather than harmful.

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 add real value: the return shape ({items, remaining}), the fact that file content is only included for text files, and the gating prerequisite. However it is silent on whether fetching advances an internal cursor, whether the call is read-only/non-destructive, and what governs what counts as the 'next' batch — ambiguity that matters for a batch/paging 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?

It is short and front-loads the purpose, then workflow, then return shape. The one structural flaw is that the critical prerequisite 'Plan must be approved before calling' sits at the very end, where an agent skimming may miss it; it belongs first.

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

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

There is no output schema, and the description compensates by declaring the response shape and the text-file content caveat. It also gives the full downstream workflow and the approval gate, which is everything an agent needs to call this correctly in sequence.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the description correctly adds none and instead spends its words on behavior. Baseline for a parameterless tool is 4.

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

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

The first sentence gives a specific verb and resource ('Return the next batch of content-category items'), plus scope qualifiers ('next batch', 'content-category') that separate it from a full-inbox scan. It does not name sibling tools like scan_inbox or execute_inbox_file_batch, so the differentiation is partial 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?

It states a hard prerequisite ('Plan must be approved before calling') and an explicit workflow (classify, summarize, call write_vault, then update_inbox_item), which tells an agent a lot about where this sits in a pipeline. The gap is that it never says when NOT to use it or how it differs from scan_inbox / get_inbox_plan / execute_inbox_file_batch, which are adjacent siblings.

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

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

With no annotations, the description carries the full burden and does well: it discloses the empty-state response {status: 'no-plan'} and enumerates the returned fields (status, budget_per_run, progress, next items per category). It does not state that it is strictly read-only/side-effect free or what happens if no inbox exists, which keeps it below a 5.

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

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

Three short lines, front-loaded with the core action, then the null-state behavior, then the returned fields. No filler or repetition; every sentence adds information an agent would otherwise have to discover by calling it.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description supplies exactly the missing pieces: the shape of a successful response and the sentinel empty-plan response. Nothing essential an agent needs before calling it is 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?

Zero parameters, so the schema baseline applies and there is no parameter meaning to add. The description correctly avoids inventing parameter claims and instead spends its space on return 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?

"Return the current inbox plan and progress" names a specific verb (return/read) and resource (inbox plan), which cleanly separates it from siblings like approve_inbox_plan and execute_inbox_file_batch that mutate or act on the plan. It stops short of naming a sibling or stating scope boundaries explicitly, so it is clear but not fully differentiated.

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

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

Usage is only implied: an agent can infer this is the read step of the plan workflow, and the documented {status: 'no-plan'} case signals it is used to check plan state before acting. No explicit when-to-use, no prerequisites (e.g. whether a vault root must be set), and no named alternatives such as approve_inbox_plan or get_inbox_content_batch.

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 supplied, so the description carries the full burden, and it does real work: it declares the return structure ({commit, author, date, subject}), recency ordering, the model that every vault write is one commit, and that a UID still resolves for deleted nodes via the file it last lived in. It stops short of stating that the operation is non-mutating, whether history is capped or how the limit truncates results.

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 blocks: return shape first, then accepted path forms, then usage and next steps. Every sentence adds information — no restatement of the name or 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?

With no output schema, the description correctly takes responsibility for explaining the return value, and it covers the identity-resolution edge case for deleted nodes. It is slightly incomplete for a 2-parameter tool because the limit default and truncation behavior go unexplained.

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 so well for `path` by naming the three accepted forms (UID, absolute path, vault-relative path). The second parameter, `limit`, is never mentioned, so its meaning (and what happens when history exceeds it) is undocumented in both the schema and the prose.

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

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

The description opens with a specific verb and resource ("List the commits that changed a node") plus ordering ("newest first") and even shows the return shape. That is enough for an agent to tell this apart from siblings such as list_vault, query_recent, diff_vault and restore_vault 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?

It gives a concrete trigger scenario ("when content is missing after a write") and a follow-up chain (diff_vault to see the change, restore_vault to undo it), which is unusually actionable routing. It does not state when NOT to use it — for example versus list_vault or query_recent for broader history — so it falls short of full exclusion guidance.

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

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

With no annotations provided, the description carries the full burden and does substantial work: it discloses the two result classes (errors vs warnings), their subcategories, and the contents of stats.tags. It never explicitly states that the operation is read-only and makes no changes to the vault, which is the main remaining gap for a mutation-adjacent concept.

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

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

Front-loaded with the core action, then structured into errors, warnings, and stats.tags. The long parenthetical enumerations are information-dense rather than repetitive, though they could be tightened slightly.

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

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

There is no output schema, yet the description explains the return shape (errors, warnings with their causes, stats.tags census fields) thoroughly enough that an agent knows what to expect. For a parameterless lint tool, nothing essential is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. No misleading parameter language is present.

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

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

Opens with a specific verb+resource statement ('Lint all vault files against the Loci schema') and then enumerates exactly what it detects (schema violations, unknown types, bad/duplicate uids, dangling relations, duplicate tags). This is clearly distinguishable from a single-node validator like validate_type or check_duplicate.

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 run it: 'after manual vault edits or when debugging unexpected behavior.' That gives a concrete trigger. It does not name an alternative or say when not to use it (e.g., versus validate_type for a single node), so it stops short of a 5.

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

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

With no annotations, the description carries the full burden, and it does disclose the return shape and the non-obvious condition where a '_notice' key appears after startup meta updates. It omits other meaningful behavior: whether listing is recursive, how results are ordered, and what happens when an unknown type is supplied.

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

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

Four short lines, front-loaded with the action, then the argument default, then the return contract. No filler sentences, though 'vault type folder' is a slightly opaque phrase that could have been clarified at no length cost.

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

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

There is no output schema, and the description supplies the return shape as a type_name-to-filenames mapping, which is the key missing piece. Combined with the notice caveat that is adequate for a simple one-parameter list tool, with only ordering and recursion 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% and the 'type' property has no description, so the description must compensate. It explains the omission semantics (list all folders) but never explains what a 'type folder' is or what valid type names look like, leaving the core filtering argument under-specified.

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

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

The description names a concrete verb ('List') and scope ('items in a vault type folder'), which is clearly distinct from mutation siblings like write_vault or patch_vault. It does not explicitly contrast with read_vault, search_vault, or find_nodes, so the differentiation from read-style siblings is left partly 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?

'Omit type to list all folders' tells the agent how to broaden the call, which is real usage guidance for the one decision the tool involves. However, it never says when to prefer this over search_vault, find_nodes, or read_vault, and gives no guidance on the type argument's valid values.

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

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

With no annotations, the description carries the full burden and discloses key behavior: updated_at is always bumped, body keys in updates are rerouted or clear the body, stale body frontmatter is stripped, and warnings arrive after the write has already happened. It also explains the warning categories and that the caller should surface them.

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

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

The description is well structured and front-loaded with purpose, workflow, args, and returns. It is somewhat long, especially the warning catalog, but nearly all details are useful given the absence of annotations and schema descriptions.

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

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

For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is complete enough to invoke correctly. It covers prerequisites, argument semantics, side effects, body handling, and return/warning behavior.

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

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

Schema coverage is 0%, so the description must compensate, and it does: path accepts UID, absolute path, or vault-relative path with a preference for UID; updates requires complete new values and examples; body replaces full body text and must not be passed inside updates.

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: patch frontmatter fields on an existing vault item. It also distinguishes itself from a full-file write by saying it works without rewriting the whole file.

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

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

It clearly says to use this for correcting or extending an existing item, gives examples, and supplies a read-then-patch workflow. It lacks explicit naming of when to prefer write_vault or other alternatives, 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?

No annotations are supplied, so the description carries the full burden. It signals a read-only analytical operation ('surface', 'finds') and describes the per-entry fields, which is helpful, but it says nothing about result ordering, whether the limit is applied before or after ranking by degree, or how 'domain' is determined. Those are the behavioral details that would matter most for a ranking-style query.

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

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

The core purpose is front-loaded in the first sentence and the second sentence sharpens it. The 'Each entry: {uid, title, type, ...}' line largely duplicates the existing output schema and is the one part that does not earn its place, though it is short.

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

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

Because an output schema exists, the return-value enumeration is redundant rather than compensating. What remains missing is the semantics of the ranking and the meaning of 'domain' and 'degree' in this vault model — the things an agent needs to interpret results correctly. Adequate, but with real gaps for an analytical query 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%, so the description must compensate, and it does: 'limit: Maximum number of bridge nodes to return (default 10)' explains the unit of the limit (bridge nodes, not raw edges) and restates the default. With only one optional parameter, this is nearly complete; the only omission is whether limit truncates a sorted result set.

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 analytical operation and defines its scope precisely: 'Surface vault nodes that bridge different domains' plus a definition of bridge nodes as nodes 'connected to items from domains outside their own.' This is enough for an agent to tell it apart from query_neighbors, query_related, query_path, and find_nodes on conceptual grounds, but it never explicitly contrasts itself with those siblings, so a 4 rather than 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?

The 'unexpected cross-domain links that reveal non-obvious patterns' framing implies an exploratory use case, but there is no explicit when-to-use statement, no when-not condition, and no named alternative. An agent must infer that this is for discovery rather than for tracing a known relation.

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 convey that this is a pure read and that both edge directions are included with relation type. It says nothing about behavior for a nonexistent or isolated uid (empty result vs error), nor about permissions or result size for high-degree nodes.

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, front-loaded with the core behavior and scope. The entry-field enumeration mildly duplicates the existing output schema, but it is compact and does no harm.

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

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

For a one-parameter read tool with an output schema already describing return values, the description covers scope, edge direction, and relation typing adequately. The only meaningful gap is error/empty-result behavior, which is a minor omission at this complexity.

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

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

Schema coverage is 0% — the single 'uid' parameter has no description. The description partially compensates by implying the uid identifies 'a vault node', but it doesn't say whether it is a bare uid, a path, or a prefixed identifier, nor where such a uid comes from (e.g. generate_uid or find_nodes).

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 direct neighbors of a vault node') and pins down scope with 'one hop only', which implicitly separates it from multi-hop siblings like query_path and query_related. It never names those siblings explicitly, so differentiation is inferred rather than stated.

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?

'One hop only' implies the boundary against traversal tools, giving implied usage guidance, but there is no explicit when-to-use/when-not statement and no alternative tool is named. An agent must infer that query_path is the right call for deeper traversal.

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 usefully states that an empty list is returned when no path exists and defines each entry as {uid, title, type}, but it does not clarify whether the path includes the endpoints, whether the graph is directed, how ties are broken, or what happens with invalid UIDs.

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

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

The description is three short sentences, front-loaded with the core purpose. It includes the return shape and empty-result behavior without unnecessary wording.

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 fully explain return values, though it does describe the entry shape. For a simple two-parameter query tool, the definition is adequate but leaves gaps around parameter meaning, directedness, and usage relative to sibling query tools.

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

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

Schema description coverage is 0%, so the description should compensate for the undocumented uid_from and uid_to parameters. It only says the tool works between two vault nodes, which weakly implies the parameters are node UIDs, but it adds no clarity about directionality, UID format, or endpoint inclusion.

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: it returns the shortest path between two vault nodes. It also describes the return shape, which makes the tool distinct from neighbors/related queries, but it does not explicitly contrast itself with sibling tools like query_neighbors or find_nodes.

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 name and description: use this tool when you need the shortest path between two known nodes. There is no explicit guidance about when not to use it or which sibling tool to choose instead, so an agent must infer the boundaries.

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

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

With no annotations, the description carries the full disclosure burden. It does well on defaults and filter semantics (active excludes archived, None shows all) and implies a read-only operation via 'Return', but says nothing about ordering guarantees, truncation behavior when limit is hit, or what happens with very large day windows.

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

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

Front-loaded with the core action, then a use case, then a compact Args block. Minor waste in restating default values that already exist in the schema, but the structure is easy to scan and contains 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 three-parameter read query this is nearly sufficient: purpose, defaults, and filter semantics are all covered, and the existence of an output schema means the inline entry shape is a bonus rather than a necessity. The remaining gap is ordering and result-cap behavior when limit is reached.

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 largely does: it defines days as a look-back window, limit as a result cap, and most importantly explains the tri-state semantics of state (active/archived/None) that the schema's bare string type leaves completely undefined. It loses a point only for not clarifying edge cases like negative or zero values.

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 most recently updated vault nodes,' which immediately distinguishes it from retrieval siblings like read_vault or list_vault. The recency framing plus one concrete use case makes the purpose clear, though it never explicitly contrasts itself with find_nodes or search_vault.

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 one concrete triggering question ('what have I been thinking about lately?'), which gives implied usage context. It does not state when to prefer a sibling such as search_vault, find_nodes, or query_insights instead, nor any prerequisites, leaving selection 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 supplied, so the description carries the full burden. It does add real behavioral detail: results are sorted nearest-first and include a distance field, which tells the agent how to consume output. It omits important behavior for a traversal tool — which relations/edge types are followed, cycle handling, what happens for an unknown uid, and whether depth is capped.

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, front-loaded with the core action, then ordering, then result shape. Every sentence adds information and none is redundant.

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

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

An output schema exists, so the description needn't explain return values further, and the entry-shape line is a helpful summary rather than filler. Given no annotations on a read/traversal tool, the remaining gap is graph semantics — edge types traversed and edge cases — but the essentials for calling it correctly are present.

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

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

Schema coverage is 0%, so both parameters (uid, depth) are undocumented in the schema. The description partially compensates: it defines `depth` as hop count from the origin and clarifies that `uid` is the origin node. It does not state the default value of depth, what depth=0 means, or the uid format, so the compensation is incomplete.

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

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

The description opens with a specific verb and resource ("Return all vault nodes within `depth` hops of the given uid"), which is unambiguous about the operation. It does not, however, distinguish itself from siblings like query_neighbors, query_path, or find_nodes, which an agent must choose between.

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 when-to-use guidance, no statement of when not to use it, and no mention of the obvious alternatives (query_neighbors, query_path, find_nodes, query_recent). The graph-traversal intent is only implied by the phrase "hops," leaving the agent to guess at routing.

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

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

With no annotations, the description carries the full burden, and it does an unusual amount: it discloses that config is answerable with no vault configured and therefore explains why the other tools are refusing, and it flags read-before-write prerequisites for several files. It stops short of stating failure behavior for an unknown file value or whether the read is unconditional, so the safety profile is strong but not complete.

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 per-value notes are information-dense rather than padded. The cost is mild redundancy: the bare file enumeration up front duplicates the keys of the annotated list below it, and the trailing-pipe formatting adds noise.

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

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

A one-parameter selector with an output schema in place needs exactly the per-value routing table provided here; return formatting is rightly omitted. Nothing required to choose the correct file value 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% and the single `file` parameter has no enum, so the description must supply all value semantics — and it does, enumerating all fifteen valid values with what each contains and when to read it. This is the rare case where the description fully absorbs a schema 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?

"Read a vault meta file" is a specific verb+resource, and the enumerated file keys make the scope concrete rather than generic. It implicitly separates meta reads from node reads (e.g. "for structure, read ontology instead") but never names read_vault as the counterpart for node content, so sibling differentiation is only partial.

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?

Nearly every entry states a condition for use: "Read with type-dictionary when classifying", "Read before writing a node of a user-defined type", "Read before constructing any has_asset entry". It also gives an explicit when-not with an alternative ("when the user asks how the ontology works rather than what a specific type requires — for structure, read ontology instead"), which is exactly the routing an agent needs.

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 supplied, so the description carries the full burden, and it discloses two non-obvious traits: it works without a configured vault, and the user's additions only load once a vault exists. It stops short of stating side-effect profile (read-only) or whether the procedure text can vary per skill, but the conditional behavior 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-loaded with the definition, then the value list, then the vault caveat — a sensible order with little waste. The sentence "Answers without a vault too" is verbless and slightly cryptic, and the value list sits awkwardly between the two prose blocks.

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

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

With one optional parameter and an output schema covering return values, the description supplies enough to call it correctly and to know how to treat the result. The main omission is per-skill meaning, which matters because the parameter is the sole input.

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 defines no enum, so the description's inline list (loci-save | loci-query | loci-inbox | loci-ingest-directory) is the only source of valid values — a substantial contribution. The gap is that it never explains what each skill does, so an agent can pick a valid value but not necessarily the right one; the default of loci-save is also 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 and resource ("Read a Loci skill") and clarifies what a skill is — "the packaged procedure with the user's own additions appended" — which an agent could not infer from the name alone. It is distinguishable from the sibling write_skill, though the distinction is implied rather than stated.

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?

"Follow the returned document for the whole interaction" is an explicit usage directive that frames this as an entry point whose output governs subsequent behavior. It also clarifies the vault-free case, but never explicitly contrasts with write_skill or says when NOT to call it.

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 and does so well: it discloses automatic path resolution, that a commit hash returns the historical version even for changed or deleted nodes, and the non-obvious "~1" suffix convention for retrieving a pre-deletion version. Gaps remain on error behavior for missing or unresolvable paths and on any vault_root prerequisite.

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 action and preferred input form are front-loaded in the first three lines, then the optional commit behavior is layered beneath. Every clause adds usable detail — no restatement of the name and no filler.

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

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

Return values need not be described because an output schema exists, and the tricky historical-read semantics are fully covered. The remaining gap is edge-case behavior — what happens for a nonexistent path, an ambiguous UID, or a commit that predates the file.

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 supply all parameter meaning and it does: path is defined as an 8-character hex UID, an absolute path, or a vault_root-relative path, with a concrete example of each. commit is defined as a hash from history_vault plus the special "~1" form for deleted nodes, information present nowhere in the schema.

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

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

States a specific verb+resource ("Read a vault file") and immediately enumerates the three accepted path forms, so the agent knows exactly what the tool consumes. It does not explicitly contrast itself with near siblings like read_meta, history_vault, or read_skill, which keeps it short of a 5.

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

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

Gives a concrete preference rule ("Prefer passing the UID when you have it — the path will be resolved automatically") and points at history_vault as the source of the commit hash, which is real cross-tool routing guidance. It stops short of stating when not to use this tool versus alternatives such as read_meta or search_vault.

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 supplied, so the description carries the full burden. It usefully discloses the return shape {path, mime_type, format, size_bytes} and the has_asset precondition, but says nothing about failure behavior when a UID has no asset, whether the path is absolute or vault-relative, or any permission/IO cost of resolving.

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 lines, front-loaded with the core purpose, then the return shape, then the usage condition. No filler or redundant restatement of the tool name.

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

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

With no annotations and no output schema, the description does well to state the return fields. However, the undocumented 'format' parameter and the absence of any error/edge-case behavior leave an agent without enough to invoke it confidently in non-happy-path cases.

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% with two parameters, so the description must compensate. It clarifies that 'uid' is an asset UID, but the 'format' parameter is never mentioned at all — its purpose (output conversion? filter? default null) is left entirely ambiguous.

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: 'Resolve an asset UID to its file path and metadata', and names the returned fields. An agent can distinguish it from write/save_asset siblings by the read-only 'resolve' framing, 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?

Gives an explicit trigger condition: 'Use this when you need the physical file location for a vault node with has_asset: true.' That is a concrete precondition, but it names no alternatives (e.g., find_unregistered_assets) or exclusions.

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

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

With no annotations supplied, the description carries the full disclosure burden, and it does real work: matching is case- and whitespace-insensitive against titles and aliases, the default scope is every active node, and `via` distinguishes title/alias/partial matches with guidance on interpreting each. It never states that the operation is read-only or non-mutating, though the surrounding 'returns found/missing' framing strongly implies it.

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

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

Front-loaded with purpose, then usage, then a structured Returns block and Args block — the organization is easy to scan. There is mild redundancy, since the `via` and duplicate-name semantics are explained in prose right after being shown in the return shape, but no sentence is wasted.

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

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

For a two-parameter tool with no output schema and 0% schema coverage, the description covers purpose, call pattern, default scope, matching rules, return shape, and result-interpretation edge cases. Nothing an agent needs to call or interpret it correctly appears to be 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 supply all parameter meaning and does: `names` is defined as names as they appear in the content (and the batching expectation), while `types` is optional, takes node-type strings with examples, and omitting it searches every active node. That is meaning well beyond the bare array schemas.

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: matching names mentioned in content against existing vault nodes' titles and aliases, with the concrete motivation (avoiding a duplicate "John Smith"). What's missing is explicit differentiation from overlapping siblings such as check_duplicate, find_nodes and search_vault, which an agent could reasonably confuse with this 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?

Gives an explicit operational rule — extract every proper name from the content first, then pass them all in a single call — which is actionable usage guidance rather than vague implication. It also tells the agent how to act on results (confirm partial hits, ask the user when a name matched several nodes), but never names an alternative tool or a when-not condition.

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 supplied, the description carries the full burden and does so: it discloses that a restore is recorded as a new commit, that nothing is lost, that it is itself undoable, that it may drop post-damage changes, and that no user confirmation is required. It even lists the return payload fields, which no output schema provides.

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

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

Front-loaded with the core action, then a clearly numbered caution list and a special-case paragraph; every section is scannable and purposeful. It is longer than most definitions but the length is justified by the safety instructions, with only slight redundancy between the numbered items and the closing return description.

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 mutation with no annotations and no output schema, the description covers the mutation's safety profile, the consent policy, prerequisites, the destructive edge case, and the return shape. Nothing an agent needs in order to call this correctly or safely 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 it largely does: it explains that 'path' may be the node's UID when restoring a deletion, and that 'commit' takes a commit hash with a '~1' suffix to indicate the deleting commit, with a concrete example. Minor gap: it never clarifies what 'commit' means in the ordinary non-deletion case (e.g., whether it accepts HEAD or only full hashes).

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 ('Put a node back as it was right after commit') and immediately names the two motivating cases: repairing a damaged node and resurrecting a deleted one. An agent can distinguish this from sibling mutations like write_vault, patch_vault, and undo_last_vault_change from the text 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?

Explicitly gives when-to-use (repair damage, restore deletion) and when-to-stop, including a numbered prerequisite flow (read_vault with commit first) and a named alternative (read_vault + patch_vault) for the case where newer changes must be preserved. It also states the user-consent boundary, which is exactly the routing information an agent needs.

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 supplied the description carries the full burden and does: it discloses the crash-safe write, the exact success return shape {uid, asset_path, vault_path}, the tag_warnings condition, and the duplicate short-circuit return {duplicate: true, uid, path, name, message} with instructions to escalate to the user. It also states that 'it writes nothing' on duplicate, which is the key irreversible-behavior fact 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?

Front-loaded with purpose, return shape, and the duplicate decision before the detail, then cleanly sectioned into mode selection and Args. It is long, and the Args block partly restates prose that appears above (source_path vs content, allow_duplicate), so it is a touch repetitive rather than wasteful.

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

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

For a 16-parameter mutation tool with no annotations and no output schema, the description supplies everything needed: return values, duplicate semantics, the two input modes and their constraints, and per-parameter meaning. Nothing material is left for the agent to guess before calling it.

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

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

Schema description coverage is 0%, so the Args block is the only source of parameter meaning and it delivers: it covers all 16 parameters, enumerates subtype values per node_type ('book'/'video'/... vs 'report'/'transcript'/... with 'note' as default), gives format and mime_type examples, constrains tags to '3-6 freeform lowercase hyphenated tags', and describes relations as {uid, type} dicts. This adds substantial meaning the bare schema lacks.

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

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

States a specific verb and resource: 'Save a new binary/rich-file asset with its vault proxy node', and calls out that it runs the same crash-safe sequence and duplicate detection as write_vault. An agent can tell it apart from write_vault, though the overlap (node_type may be 'document') and the unmentioned asset-specific siblings like resolve_asset and find_unregistered_assets keep it short of a perfect 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 'Choosing the right mode' block: use source_path whenever the file exists on disk, use content only for material already in context, and a hard exclusion ('Never base64-encode a file yourself just to pass it here'). It also prescribes the duplicate-handling workflow — ask the user to update or save a copy, and only then re-call with allow_duplicate=true.

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

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

With no annotations, the description carries the burden and does well: it discloses the exact matching rule (a has_asset location with scheme: local pointing at the resolved absolute path) and warns that suggested_type and suggested_title derive from the filename alone and may be wrong. It does not cover error behavior for missing/unreadable paths, symlink handling, or depth of recursion, which keeps it below a 5.

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

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

Front-loaded with the purpose, then the matching rule, then a structured return shape, then args; each block is scannable. The suggested_type/subtype paragraph is slightly verbose for what it conveys but earns its place as a caution about derived values.

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

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

There is no output schema and no annotations, yet the description supplies a full return shape (directory, total_files, unregistered, registered with field lists), which is exactly what an agent needs to consume results. Remaining gaps are edge-case behavior on bad paths and recursion limits, minor for a read-only scanning tool.

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

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

Schema coverage is 0%, so the description must compensate, and it does for both parameters: path is specified as an absolute directory path and recursive is explained as scanning subdirectories, including its default. The absolute-path requirement and subdirectory semantics are genuine additions the schema does not provide.

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 line gives a specific verb and resource (scan a directory for files) plus the distinguishing outcome (identify which already have vault nodes). It is clear on its own, but among siblings such as find_unregistered_assets and scan_inbox there is no explicit statement of how this differs from those overlapping 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?

Usage is implied: you scan a directory to find unregistered files before saving them as assets, and the description advises confirming suggested_type/suggested_title with the user when they look wrong. However, it never names an alternative (e.g. find_unregistered_assets, scan_inbox) or states when not to use this tool, leaving the agent to infer selection.

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

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

With no annotations, the description carries the full burden and mostly meets it: it discloses the write side effect (creates/overwrites .inbox-plan.yaml), scopes it (no files moved, no vault nodes created), and even spells out the return payload. The phrase "Read-only" sits in mild tension with the fact that it writes and can clobber an existing plan, but the overwrite is called out explicitly in the same block, so an agent is not misled.

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

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

Four short lines, front-loaded with the phase and action, followed by side-effect scope, return shape, and ordering. No sentence is filler, and the return-shape line is warranted because no output schema exists.

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

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

Complete for a parameterless workflow step: it explains what is scanned, what is written, what is not touched, what comes back (substituting for the absent output schema), and when to call it. The only omission is a pointer to get_inbox_plan() for inspecting an existing plan prior to an overwrite.

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

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

The tool takes zero parameters, so there is no parameter meaning to convey; the baseline for a parameterless tool applies. The description correctly implies no inputs are needed by describing the scan as operating on a fixed directory.

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 (scan loci-stage/), names the workflow phase it belongs to, and says exactly what artifact it produces (.inbox-plan.yaml). The classification step and the plan-file output make it clearly distinguishable from siblings like scan_directory or get_inbox_plan.

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

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

Gives explicit ordering guidance ("Call this before approve_inbox_plan()") and warns about the overwrite condition, which is exactly the when-to-call context an agent needs. It does not mention get_inbox_plan() as the way to inspect an existing plan before triggering an overwrite, leaving one routing decision 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 supplied, so the description carries the full burden. It does disclose useful behavior: case-insensitive substring matching, the default exclusion of archived nodes, and the shape of each returned entry. It says nothing about result limits, ordering, pagination, or permissions, which matter for a search 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-loaded with the core action and use case, then a compact Args block. Slight redundancy in restating 'case-insensitive substring match' for query after already stating it in the opening line, but nothing is wasted overall.

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

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

An output schema exists, so return values need not be explained, yet the description still lists the entry fields helpfully. For a two-parameter read tool this is nearly complete; only search limits and ordering are 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 largely does: query is defined as a case-insensitive substring, and state is explained across all three modes (active default, archived, None for all). The only weakness is that 'None' is used where the schema type is null, a minor wording mismatch.

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 vault nodes by title and summary text') plus the matching semantics (case-insensitive substring). It also scopes the tool to the case where a keyword is known but the exact title or uid is not, which separates it from exact-lookup siblings like read_vault, though it never names a sibling explicitly.

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

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

Gives a clear use condition ('when you know a keyword but not the exact title or uid') and explains the state filter's three modes with the default spelled out. It stops short of naming alternatives such as find_nodes or list_vault or saying when not to use it.

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

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

With no annotations, the description carries the full burden and does so: it states the side effects (records the path, creates and seeds the directory), that changes take effect immediately with no restart, that the failed call can be retried, that a `notice` may be returned when files are moved, and the exact failure condition for managed installs.

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 critical facts (what it does, when to call, immediate effect) are front-loaded, and the Args section is precise. The middle paragraph on asking the user for a path is longer than strictly necessary, though it is genuinely operational guidance rather than filler.

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

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

There is no output schema, but the description enumerates the return fields ({vault_root, created, configured_at} plus optional `notice`) and instructs the agent to relay the notice verbatim. For a two-parameter configuration tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: `path` is documented as an absolute path with `~` expansion, and `create` is explained with its False semantics (adopt an existing vault only; any other path fails without writing anything). This adds meaning well 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 opens with a specific verb and resource: 'Point Loci at the user's vault directory.' It also names the return shape and distinguishes this configuration tool from the many vault read/write siblings by framing it as the setup step that makes them work.

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

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

It gives explicit triggers ('when a tool has failed with LOCI_NOT_CONFIGURED', 'when the user asks to move Loci to a different vault') and an explicit exclusion ('Fails when the deployment sets LOCI_VAULT_ROOT... cannot be changed from chat'). It also prescribes the interaction protocol: ask for the path first, never guess, never offer a default.

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 supplied, the description carries the full burden and does so: it discloses that the undo is itself recorded as a new commit (so calling again redoes the change), that a stale `commit` causes nothing to be undone plus an error, and what the mutation does node-by-node.

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?

Roughly ninety words, front-loaded with the core action before alternatives and edge cases. Every sentence adds information: semantics, trigger, fallback, parameter rule, and return shape.

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

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

For a single-parameter mutation tool with no output schema, it covers semantics, error behavior, and the return payload name list. The one uncovered case is what happens when the vault has no commit to undo, which an agent would want to know.

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: `commit` is identified as the hash returned by the bad write, with a minimum length of 7 characters, an omitted-value default (newest commit), and a precise stale-hash failure mode.

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

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

The description names a specific verb and resource (undo the newest vault commit) and then spells out the per-node semantics: a created node is removed, a changed or deleted node is restored. It explicitly distinguishes itself from history_vault and restore_vault, so an agent can route correctly 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?

It gives an explicit trigger ('Use it right after a write that went wrong') and an explicit exclusion with the alternative to use instead when later writes have landed. It also pins down when the `commit` argument should be supplied, which is the main selection nuance for 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 disclose real consequences: status="skipped" drops the item, pending with allow_duplicate causes a second copy to be saved by the next batch, and the plan stays incomplete while an item is parked. It omits error behavior, idempotency, and whether status changes are reversible, 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?

The purpose is front-loaded, followed by scenario-specific guidance and an Args block. The Args block partially restates schema parameter names, but each entry adds semantics, so little is wasted; the multi-line case guidance is justified by the branching logic.

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

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

For a mutation tool with no annotations and no output schema, the description supplies the workflow position, prerequisite ordering, and side effects of each status, which is most of what an agent needs. Missing pieces are return/confirmation behavior and failure handling, keeping it just below 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 enumerates the four status values, marks uid as required when status='done', states path is relative within loci-stage as it appears in the plan, and explains allow_duplicate's effect. All four parameters gain meaning beyond their 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?

The description opens with a specific verb+resource statement ('Update a plan item's status'), which is clear and distinct from vault-writing siblings like write_vault or patch_vault. It does not explicitly name sibling alternatives, but the plan-item framing plus references to execute_inbox_file_batch and write-a-vault-node make the scope identifiable.

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

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

It gives concrete when-to-use guidance tied to workflow position: 'call after writing a vault node for the item' for content items, and a decision rule for file items parked as duplicate (skipped to drop vs. pending plus allow_duplicate to re-queue). It does not explain when not to use it or cover the 'failed' status, so it falls short of full 5-level coverage.

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

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

With no annotations provided the description carries the full burden, and it does disclose that this is a non-mutating pre-check and reports the exact return shape (valid/errors/resolved_fields). It also surfaces a real constraint — the name must not collide with any canonical type — but says nothing about permissions, whether resolved_fields reflects inheritance expansion, or error 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?

One front-loaded purpose sentence, then the return contract, then a compact Args block — no filler. The Args indentation is docstring-style rather than prose, but every line supplies information absent from the 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?

For a 3-parameter tool with zero schema coverage and no output schema, the definition is nearly self-sufficient: all three parameters are explained and the return shape is inlined. What's missing is only edge behavior — e.g. whether validation is purely syntactic or resolves against the existing ontology graph.

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 do all the work, and it does: name is documented with its collision constraint, extends with concrete canonical examples ("procedure", "task"), and fields with its item shape, the allowed type values, and the enum-specific 'values' requirement. This is meaningfully more than the bare schema conveys.

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

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

The description opens with a specific verb and resource: validate a proposed user-defined type, scoped to the target artifact ontology-user.yaml, and frames it as a pre-write check. That distinguishes it reasonably well from the sibling define_type (which presumably performs the write), though it never names define_type explicitly.

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

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

It states a clear usage context — call this before writing the type to ontology-user.yaml — which tells an agent where this fits in the workflow. It stops short of explicit exclusions or naming the write-path sibling as the alternative, so it lands just under a full 5.

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

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

With no annotations supplied, the description carries the full burden, and it does disclose the key trait: this is a destructive full overwrite, not an append, which is why it demands a read-append-write cycle. It does not mention required permissions, whether content is validated before writing, or any recovery path despite siblings like undo_last_vault_change existing.

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 lines, front-loaded with the core action, then the enumerated targets, then the one workflow that needs explanation. No sentence is filler and no repetition of the 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 return values need not be described, and for a two-parameter tool the description covers target values, overwrite semantics, and the correct pre-write sequence. The remaining gap is that the content shape for tag-dictionary and foreign-definitions is never described, leaving those two code paths underspecified.

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

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

Schema description coverage is 0% and the schema gives only bare titles, so the description must compensate — and it largely does, spelling out the accepted values for 'file' and clarifying that 'content' is full YAML that replaces the file rather than a diff. Format specifics and validation expectations for the other two file types remain 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 opens with a specific verb and resource ('Overwrite a vault meta file') and enumerates the three valid targets (tag-dictionary | foreign-definitions | ontology-user), so an agent immediately knows the operation and scope. It stops short of naming how it relates to the many sibling writers (write_vault, patch_vault), which keeps it just below top marks.

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?

For ontology-user the guidance is explicit and mandatory: read first with read_meta, append the entry, then write the full content here. However, no guidance at all is given for the other two valid file values (tag-dictionary, foreign-definitions), and there is no statement of when to prefer this over patch_vault or write_vault, so the coverage is partial.

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

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

With no annotations, the description carries the full burden and does so: it discloses the destructive default (whole-file replacement unless append=True), explains the separate lifecycle of packaged vs. vault-stored content across upgrades, and states that changes take effect on the next read with no reinstall. That is exactly the behavioral context an agent needs before calling a mutation.

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 and location in the first sentence, then adds constraints in a compact block. A few phrasings are slightly mannered ('survive one', 'Nothing to reinstall'), but each sentence still conveys a distinct, load-bearing fact.

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-parameter mutation tool with an output schema, the description covers overwrite semantics, the permitted skills, and the effect on subsequent reads. Remaining gaps are minor: no guidance on failure behavior for an invalid skill name or whether content must be markdown.

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 description compensates: it enumerates the valid skill values (loci-save, loci-query, loci-inbox, loci-ingest-directory) which the schema does not, and explains the append flag's meaning against the default overwrite. The content parameter is only implied as the additions text, not explicitly characterized.

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: writing the user's additions to a Loci skill, and pins down the exact storage location (vault/skills/<skill>.md). It also identifies the counterpart tool read_skill and the section it manages, so the agent can distinguish it from generic vault writers.

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 precondition — read the current additions via read_skill before rewriting — and an explicit alternative path (append=True for whole-file replacement). It also states what is not writable (the packaged procedure). It does not, however, contrast itself with sibling writers like write_vault or write_meta for an agent that might reach for a generic writer.

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 present, the description carries the full burden and does so: it discloses that duplicates cause nothing to be written and returns a {duplicate: true, ...} shape, that tag_warnings are advisory rather than blocking, that a body key in extra_fields is rerouted, and that a conflicting uid is refused with {errors}. The only notable omission is irreversibility/undo (undo_last_vault_change exists but is not mentioned).

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?

Long but organized: behavior and return shape first, then the duplicate workflow, then an arg-by-arg list. The prose is mostly load-bearing, though a few lines (e.g., the repeated emphasis on tag_warnings being advisory and 'The write has already happened') 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?

For an 11-parameter mutation tool with no output schema and no annotations, the description supplies both return shapes (success and duplicate), the error case, and full argument semantics. An agent has everything needed to call it correctly and handle both outcomes.

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

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

Schema description coverage is 0% and the schema has no enums, so the description must compensate — and it does: it enumerates all valid type values, all domain values, tags conventions ('3-6 freeform lowercase hyphenated'), author conventions, and the shape of relations/references dicts. It also explains the non-obvious extra_fields/body/uid interactions. This is meaning the schema alone cannot supply.

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

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

Opens with a specific verb+resource: 'Write a new item to the Loci vault.' It also makes the read/write boundary explicit versus patch_vault for updates. It does not distinguish itself from write_skill, save_asset, or write_meta, so a sibling ambiguity remains for a few edge cases.

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

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

Gives explicit when-to-use routing: on duplicate, ask the user whether to update via patch_vault or re-call with allow_duplicate=true, and gates allow_duplicate to only after the user picks 'save as new'. It also tells the agent what to do with tag_warnings (surface and offer the fix). This is a full when/when-not/alternatives treatment.

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