loreweave

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 declares determinism, the return envelope {groups, totalGroups, limit}, and the critical interpretation rule that groups is truncated to limit while totalGroups is the true count. It omits cost/performance characteristics and any permission or auth notes, which keeps it short of a 5.

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

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

Three sentences, each earning its place: purpose first, then the routing rule, then the return-value caveat. The totalGroups pitfall is front-loaded where an agent will read it before writing code.

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

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

There is no output schema, so describing the return envelope and the groups-vs-totalGroups distinction is exactly the right compensation, and it is complete for calling the tool correctly. The residual gap is filter parameter syntax (especially date formats), which is not addressed anywhere.

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 only 17%, so the description must compensate, and it does so well for limit (default 100, raise it for the tail) and implies groupBy's role. However, since/until date format and the semantics of the subject/predicate filters remain undocumented in both schema and description, leaving several of the 6 parameters 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+resource ('deterministic aggregation over fact history') plus the exact grouping dimensions (object/subject/predicate) and date-range filtering. It also implicitly distinguishes itself from similarity-based siblings, so an agent can tell it apart from lore_search without opening a schema.

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

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

Gives concrete trigger questions ('how many X', 'which Y most often') and an explicit exclusion: similarity search cannot answer these reliably. This routes the agent between this tool and the search family 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 burden and does well: it discloses automatic supersession of contradicting facts, that facts are never deleted and history remains queryable, and that the fact is journalled to lore/journal/ in markdown. It omits permissions, error cases and return behavior, but the key non-obvious side effects are surfaced.

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 sentences, front-loaded with the operation and its side effects, then the usage cue. Dense but nearly every clause adds value; 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?

No output schema and no annotations, yet the description covers the mutation semantics, supersession model, and persistence location that an agent most needs. It stops short of documenting half the optional parameters, but is otherwise complete for the call.

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 only 57%, so the description should compensate more. It clarifies the subject/predicate/object triple and the bitemporal (validFrom/validUntil) intent, which helps, but says nothing about confidence or the stated/extracted/inferred sourceType beyond what the schema already documents.

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 (record) and resource (an atomic subject :: predicate :: object fact), making the operation unambiguous. It does not name sibling tools like lore_propose_facts, but the tripartite structure is enough to identify the operation.

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

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

The final sentence gives clear when-to-use context ('durable knowledge: decisions, states, preferences, relationships'). However, it offers no when-not guidance and never distinguishes this from the related sibling lore_propose_facts, leaving the routing to inference.

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

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

With no annotations, the description carries the full behavioral burden and does so well: append-only, never overwrites, never writes outside the vault, symlink escapes refused, and capture is immediately searchable. That is exactly the safety and effect profile an agent needs to decide it can call this freely.

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 sentences, front-loaded with the primary action and default target, then usage, then guarantees. No filler or repetition.

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

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

For a 2-parameter mutation tool with no annotations and no output schema, the description covers effect, safety, and semantics thoroughly. The only minor gap is that it never says what a successful call returns (path written, timestamp, etc.), which the absence of an output schema makes slightly more relevant.

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 only 50% ('text' is undocumented in the schema), but the description compensates by explaining the append-and-timestamp behavior of the content and restating the default/alternate target for 'to'. It does not cover the maxLength bounds, but the intent of both parameters is clear.

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 ('Append a timestamped line to lore/inbox.md') with the default target and an allowed override. It also implicitly distinguishes itself from lore_assert_fact by scoping to 'fleeting observations ... not atomic facts', so an agent can route between the two without reading schemas.

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

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

Explicitly says when to use it ('fleeting observations worth keeping that are not atomic facts'), which is real selection guidance. It does not name a sibling tool outright as the alternative, so the routing is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It does disclose an important behavioral trait — every list is a sample and truncated lists expose a { shown, of, rest } field pointing at the remainder tool — which is genuinely useful context about partial results. However, it says nothing about cost, latency, permissions, or whether the primer is a pure read, so the behavioral picture is incomplete rather than wrong.

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 payload list, then usage, then the truncation caveat. Dense but every sentence carries distinct information; nothing restates the name or title.

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

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

With no output schema and no annotations, the description must cover return contents and semantics — and it does, enumerating the sections and the truncation contract. An agent has everything needed to call it and interpret a partial result correctly.

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

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

Schema coverage is 100% and only one optional parameter exists, so the baseline would be 3. The description earns one extra point by explaining the parameter's effect on output ('if topic given, top search hits'), which tells the agent what changes when topic is supplied — meaning beyond the schema's 'optional focus topic'.

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

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

States a concrete verb and enumerates the exact payload: vault stats, top entities, recently modified notes, valid facts, and optional search hits. This is clearly distinguishable from siblings like lore_search (targeted hits) and lore_query_facts (fact lookup), which the description itself reinforces.

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

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

Explicitly says when to use it ('call once at session start to orient') and names the follow-on alternatives ('then drill down with lore_search / lore_read_note'). No inference required about sequencing.

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 clarifies that the vault is untouched unless apply=true, that apply writes a digest and review queue under lore/, and that index maintenance happens either way but changes no results. It does not cover auth, rate limits, or the exact format of writes, but the key mutation and side-effect behavior is disclosed.

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

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

Three sentences, front-loaded with purpose, then mutation behavior, then output verbosity. Every sentence earns its place and there is no redundancy 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?

No output schema or annotations exist, so the description must provide context. It covers the tool's purpose, side effects, parameter effects, and output verbosity (summary vs. verbose). It lacks detail on the exact return format, but for a report tool the description is sufficiently 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 50% (apply has no schema description). The description compensates by explaining that apply=true writes a digest and review queue, and that verbose=true returns every finding rather than a summary. The verbose explanation duplicates the existing schema description, but the apply clarification adds real meaning beyond the schema.

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

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

States a specific verb ('Run the consolidation pass') and resource, then enumerates the exact finding types (duplicate passages, contradicting facts, stale knowledge, missing links, orphan notes). This clearly distinguishes it from most siblings, but it does not explicitly name an alternative tool (e.g., lore_review) or state when to prefer this over them.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance. It says 'Run the consolidation pass' but does not describe the scenario that should trigger this tool versus alternatives like lore_review or lore_search. Usage is only inferred from the 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, the description carries the full behavioral burden. It usefully discloses two traits: the operation is incremental, and lore_* writes are already indexed so this call is unnecessary after them. However, it says nothing about what happens with a full reindex, whether the operation is safe or idempotent, cost/latency, or any locking or permission requirements.

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

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

Two sentences, front-loaded with the action and immediately followed by the routing rule. Every clause earns its place, including the parenthetical examples that make the condition concrete.

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, single-parameter tool with no output schema, the description covers purpose and routing well. But it leaves the only parameter unexplained and provides no behavioral notes on what 'full' does, so an agent can invoke it correctly in the common case but not fully safely in the full-reindex case.

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?

There is one parameter, 'full', with 0% schema description coverage, and the description never mentions it. The word 'Incrementally' faintly implies a non-full default, but the semantics of toggling 'full' (rebuild vs. incremental sync, cost, potential data effects) are left entirely 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?

The description pairs a specific verb ('incrementally sync') with a specific resource ('the markdown vault into the index'), and it names the sibling behavior it is not ('the lore_* write tools index their own writes'). An agent can tell exactly what this tool does and how it relates to the lore_* family without inspecting 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 gives an explicit trigger ('Call after writing files to the vault through anything OTHER than lore_* tools') and an explicit exclusion ('their content is searchable immediately without this'). The alternative cases (editor, another agent, plain fs writes) are enumerated, leaving nothing to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the operation is journalled and history-preserving, but leaves key behavioral questions unanswered: what happens if no currently-valid fact exists, whether the close is idempotent, and what validUntil does retroactively or in the future.

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

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

A single tight sentence plus a short tag; the disambiguating constraint ('without asserting a replacement') is front-loaded. Every clause earns its place.

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

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

Given a 3-parameter mutation tool with no annotations and no output schema, the description covers the core intent and the history-preservation trait but omits failure modes, validUntil semantics, and any return/confirmation behavior. Adequate but with visible gaps.

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 only 33%, so the description must compensate. It adds real value by framing subject/predicate as a slot identifier that selects the fact to close, but it adds nothing about validUntil beyond what the schema already says, leaving a third of the parameters undocumented in both places.

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

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

Names a specific verb (close/invalidate) and the exact resource scope: the currently-valid fact in a (subject, predicate) slot. The clause 'without asserting a replacement' cleanly distinguishes it from lore_assert_fact, so an agent can route between the two without opening either schema.

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

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

Gives clear usage context by contrasting with the replace/assert case ('without asserting a replacement — e.g. "no longer true"'), which implicitly defines when this tool is the right choice. It stops short of naming lore_assert_fact explicitly or stating exclusions, so it is clear but not fully prescriptive.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the effect of the call (used memories decay slower), which is real value beyond the name. However, it says nothing about idempotency, behavior on an unknown notePath/anchor, whether re-calling compounds the signal, or any auth requirement.

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

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

Two tight sentences with the action and its reinforcement signal front-loaded, then the invocation trigger. 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 simple two-parameter, no-output-schema tool this covers the essentials, but it leaves an agent guessing about the unexplained notePath parameter and error/idempotency behavior — gaps the annotations cannot fill since none are provided.

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 50% and the description explains neither parameter: notePath has no schema description and is not mentioned, and anchor is only implicitly hinted at by the word 'passages'. The description does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Reinforce passages...') and clarifies the mechanism (spaced-repetition / slower decay), which distinguishes it from read/search/review siblings. It is clear what the tool does, though it never explicitly contrasts itself with lore_review, the nearest sibling.

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 timing guidance — 'Call after citing a note' — which is exactly the moment an agent needs to invoke this. It stops short of stating when NOT to use it or naming the reinforcement alternatives (e.g., lore_review), so it is clear context without exclusions.

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

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

With no annotations, the description carries the burden and does substantial work: it discloses the engine's auto-accept rules (frontmatter, `key:: value`, `- [key] value`), why prose formatting is surfaced instead of assumed, and that only facts NOT yet stored are returned. It never explicitly states whether the call mutates the vault/index or requires auth, which is a gap for a tool feeding a write pipeline.

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

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

Front-loaded with the core purpose, then the mechanism, then the action. The closing line ('This keeps judgement with you and out of the index') is motivational rather than operational, so it burns a little space, but the rest is dense and informative.

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

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

For a two-param read/surface tool with no output schema and no annotations, the description covers what is returned, why some content is surfaced rather than auto-accepted, and the follow-up action. Only the limit parameter and the explicit side-effect/auth profile are left unaddressed.

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

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

Schema coverage is 50%: notePath is documented in the schema, limit is not. The description implies single-note vs. vault-wide sampling ('a note's structure' ... 'sample the vault') which aligns with notePath, but it says nothing about limit or how many candidates are returned by default. It partially compensates but does not close the coverage gap.

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

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

States a specific verb and resource: returns candidate facts mined from a note's structure that are not yet in the fact store. It clearly distinguishes itself from the write-side sibling lore_assert_fact by framing itself as the adjudication/surfacing step.

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

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

Explicitly routes the agent: review the returned candidates and call lore_assert_fact for the ones that are genuinely durable facts. It also explains why prose formatting lands here rather than being auto-accepted, which tells the agent when this tool's output is worth acting on.

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

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

No annotations are provided, so the description carries the full burden; it discloses the default scope (currently-valid facts), supersession-chain behavior, and the return shape including the `truncated` sampling field with its { shown, of, rest } structure. It stops short of covering auth, rate limits, or ordering, but the sampling warning is a substantive behavioral disclosure few definitions include.

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 default and the two temporal modes, then the sibling routing rule, then the return/truncation warning. Every sentence adds decision-relevant information with no filler.

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

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

For a six-parameter read tool with no output schema and no annotations, the description supplies default scope, temporal semantics, return shape, and a false-negative guard ('narrow by subject or raise limit before concluding a fact does not exist'). Predicate semantics and result ordering are the only omissions.

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

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

With schema coverage at only 50%, the description compensates well: it explains asOf, asKnownAt (including the backdating exclusion rule), includeHistory, and the limit/subject narrowing. Only `predicate` goes unexplained, a minor gap against five well-contextualized parameters.

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

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

States a specific verb and resource ('Query the bitemporal fact store') and immediately scopes the default behavior, distinguishing it from lore_search by naming the exact domain it owns (factual slots). An agent can select this over siblings without opening a schema.

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

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

Explicitly names the alternative ('Prefer this over lore_search for factual slots') with the condition that selects it, and disambiguates the two temporal modes by their question form ('what was true on DATE' vs 'what did we know on DATE'), giving when-to-use guidance for each parameter mode.

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 behavioral burden and does well: it discloses a security boundary (no reads outside the vault, symlink escapes refused) and a side effect that escaped files are not indexed or searchable. It omits error/return behavior details, so it falls short of full transparency.

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

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

Three sentences, all front-loaded and information-dense with no filler. The path constraint and the follow-up action are distinct, earning their sentences, though the middle sentence is somewhat packed.

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, no-annotation, no-output-schema read tool, the description covers the addressing scheme, a security boundary, and the intended follow-up action. An agent has enough to call it correctly; only the failure/return shape is left implicit.

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

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

Schema coverage is 100% with a single documented parameter, so baseline would be 3. The description adds value beyond the schema by specifying where the path comes from (search results) and constraining it to vault-relative, which is meaningful for correct invocation.

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 (Read) and resource (raw markdown of a note) plus the exact addressing scheme (vault-relative path). This clearly distinguishes it from lore_search or lore_context_pack, which locate rather than return raw content.

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 context for the input ('as returned in search results') and a follow-up step ('after reading a note that answered the question, call lore_mark_used'). It does not, however, state when to prefer this over lore_search or lore_context_pack.

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

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

With no annotations, the description carries the full burden and does a good job: it discloses that the call has a side effect (consuming the delta / advancing the watermark), that the result is deterministic ('the same watermark always yields the same answer'), and how to avoid the side effect. It does not describe error behavior, auth requirements, or the return envelope, so it is 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?

Three dense sentences, front-loaded with the return contents before the usage and parameter guidance. Every clause carries information; the determinism clause is the most expendable but still supports why the watermark contract matters.

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 no output schema, the description does the extra work of sketching the return contents ('notes edited, facts asserted, knowledge updates (slot: old → new)'). It omits error/failure behavior and whether the watermark is ever reset, which keeps it from being fully complete.

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

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

Schema coverage is 100% and the schema already documents `since` as an ISO watermark that does not advance the boundary, so the baseline is 3. The description earns above baseline by explaining the consequence the schema omits: omitting `since` consumes the delta and advances the watermark, while passing it is a pure read.

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

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

The description uses a specific verb-plus-resource framing ('what changed since this tool was last called: notes edited, facts asserted, and knowledge updates') that tells an agent exactly what comes back. It implicitly separates itself from pure-read siblings ('pass an explicit `since` for a pure read'), but never names a sibling tool, so it falls short of full differentiation.

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 ('call once at session start to continue where the previous session left off') and distinguishes the two modes of use, consuming vs pure read. No sibling alternatives are named, so it is a strong context statement rather than a full routing guide.

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

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

No annotations, so the description carries the full burden. It usefully discloses that results are deterministic and computed from the vault's own fitted forgetting curve, and implies a read-only listing. It does not state pagination behavior, ordering, or the shape of returned items, leaving real gaps for a no-annotation tool.

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

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

Three sentences, front-loaded with the definition of fading knowledge, then the loop mechanic, then the determinism note. No filler, though the spaced-repetition framing is slightly verbose for a list tool.

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

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

With no annotations and no output schema, the description still conveys membership criteria, expected follow-up action, and the deterministic nature. Only the returned item shape and pagination remain unspecified, which is a modest gap for a filtered-list 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 100%, so both limit and threshold are already documented with defaults and bounds. The description restates the threshold concept (

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 precisely what the tool surfaces: blocks whose retrievability decayed below threshold plus long-untouched open facts. This distinguishes it from siblings like lore_search or lore_timeline by content type, though it reads more as a description of results than a clean verb+resource.

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

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

Explicit workflow guidance: 'review the list, then call lore_mark_used on anything still relevant — use is what reinforces stability.' It names the follow-up tool and the condition for using it. No explicit when-not-to-use or alternative-tool exclusion, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the retrieval mechanism, that it returns one passage per note (the best-matching section), and what metadata accompanies it. It omits auth/permission needs and performance characteristics, keeping it out of 5 territory.

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

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

Three tight sentences with the mechanism front-loaded, then usage, then the param caveat. Dense but every clause carries information; minor cost from the parenthetical technical detail.

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

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

For a search tool with no output schema and no annotations, the description tells the agent what it gets back (passage, source file, match proportion, linking entity) and when to escalate to verbose. Missing only operational details like auth or result limits.

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

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

Schema coverage is 100%, so the schema documents all seven parameters; baseline is 3. The only added meaning is the verbose hint ("only if you need score internals"), which is a mild addition over the schema's description of score breakdown.

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 (hybrid retrieval over the markdown vault) and names the exact retrieval methods (BM25 + knowledge-graph spreading activation + dense embeddings). It also defines the return shape precisely. It does not explicitly name a sibling it differs from, so it falls short of a 5.

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

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

Gives an explicit when-to-use trigger ("any 'what do my notes say about X' question") and even the harder case (multi-hop associations sharing no words with the query). It adds a conditional param rule for verbose, but names no alternative sibling or when-not-to-use 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?

No annotations exist, so the description carries the full burden. It does disclose return composition well (each value change with what it replaced and when it stopped holding, merged with dated passages), which is genuinely useful. However, it says nothing about authorization, result size limits, pagination, or ordering guarantees for a tool that could return a large merged history.

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

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

Front-loaded with the core purpose, then examples, then the anti-pattern guidance — a logical order with little waste. The single long sentence with em-dash parentheticals is dense, slightly reducing readability.

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 usefully explains what the return contains and how the two sources merge. Date scoping lives in the schema. Adequate for a 3-param read tool, though limits/pagination on the merged result remain 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 coverage is 100%, so since/until/subject are already documented in the schema. The description's mention of 'content-dated passages' hints at temporal semantics but adds no syntax or format detail beyond the schema's ISO-date notes. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Chronological history of an entity') and precisely defines the two merged data sources (bitemporal fact-store value changes plus content-dated passages). It is clearly distinguishable from siblings like lore_query_facts and lore_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?

Explicitly frames the trigger questions ('what happened to X', 'history of X') and names the naive alternatives to avoid — repeated as-of fact queries and windowed searches. This routes the agent away from lore_query_facts/lore_search with a stated condition.

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