loci

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

With no annotations provided, the description carries the full burden. It transparently describes the retrieval, synthesis, grounding, and citation behaviors, as well as the verify audit option. However, it does not mention potential limitations (e.g., could be slow with verify, might not find relevant excerpts) or side effects, which would have made it more transparent.

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

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

The description is concise and well-structured with clear 'Behavior' and 'Usage' sections. It conveys all necessary information without redundancy or excessive 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?

The description adequately differentiates brain_ask from the sibling brain_search and explains the verify option. It covers the tool's purpose and usage context well. However, it does not mention any edge cases (e.g., what happens if no relevant excerpts are found) or input/output examples, which would make it complete.

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

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

The schema describes only the verify parameter ('audit the answer against the sources'), while the question parameter has no description in the schema. The tool description implicitly clarifies that 'question' is a natural-language query, but the descriptions are minimal and do not add much beyond the schema. Parameter semantics are adequate but not enriched.

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

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

The description clearly states the tool's function: asking a question, retrieving relevant excerpts, synthesizing an answer grounded only in those excerpts, and providing source citations. It explicitly contrasts with brain_search, making the purpose distinct and specific.

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

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

The description gives explicit usage guidance: prefer brain_ask over brain_search when synthesis or explanation is needed, and set verify=true when accuracy matters more than speed. This provides clear when-to-use and trade-off direction.

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 fully carries the behavioral disclosure burden. It explains that matching memory notes move to a .trash folder, are recoverable by hand, and that chunks leave the index immediately while nothing is permanently destroyed. This gives the agent an accurate model of consequences and reversibility.

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 tightly packed sentences: what it does, what happens behaviorally, and when to use it. Every sentence adds distinct value and the important purpose is front-loaded.

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

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

For a single-parameter, recoverable mutation tool with no output schema and no annotations, this description is complete. It covers semantics, behavior, recovery, and usage, leaving no significant gap an agent would need to resolve before invoking 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?

The schema already documents the single parameter 'query' as matching filenames or content, and the description does not add new parameter-specific semantics beyond restating matching behavior. Since schema description coverage is 100%, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource, 'Retract memories that are wrong or outdated,' which clearly identifies the tool's function. It also distinguishes itself from siblings like brain_remember and brain_search by focusing on removal/retraction rather than storage or retrieval.

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

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

The 'Usage' sentence explicitly states when to use the tool: when a remembered fact was superseded or was a mistake. It also names brain_search as the tool to consult first if uncertain, giving the agent a clear decision path.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers. It discloses both invocation modes, what each returns, that relations cite their source files, and that the graph is built from LLM-extracted triples in graph.json via `loci graph build`. This gives the agent a clear picture of behavior and data provenance.

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 concise and front-loaded: the main action is in the first sentence, followed by behavior, provenance, and usage. Every sentence contributes a distinct piece of information, and there is no filler or redundancy.

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

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

For a single-optional-parameter read tool with no output schema and no annotations, the description is complete. It explains both output modes, the return characteristics (relations with source citations, hub entities), data provenance, and the intended usage context. Nothing needed to invoke it correctly is missing.

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

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

The schema already documents the single optional parameter at 100% coverage, so the baseline is 3. The description adds meaningful semantics by tying the presence or absence of the entity parameter to different outputs: relations for a given entity versus top hub entities when omitted.

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 queries the knowledge graph over memories and wiki pages. It further specifies two concrete behaviors — returning outgoing/incoming relations for an entity or top hub entities when omitted — which makes its scope and output mode clear and distinct from siblings like brain_search and brain_ask.

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

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

The description explicitly says when to use it: explore how concepts connect before asking questions and see the strongest entities for orientation. It does not name alternative tools or state when not to use it, 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?

With no annotations, the description carries the full burden. It adds real behavioral context — summarize regenerates digest notes into a shared pool, and unchanged harnesses cost nothing — but omits whether the shared pool write is durable/reversible, whether it needs elevated permissions, and what stats returns beyond the schema's 'table'.

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 dense sentences with no filler, and the dual purpose is front-loaded. Mildly hurt by jargon ('harness', 'auto-summary note') that assumes context the agent may not have.

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 no annotations and no output schema, the description covers both modes and the cost behavior of the summarize path. It leaves the summarize side-effect and return shape under-specified, but nothing critical is missing for invocation.

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

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

Schema description coverage is 100%, so name, force, and action are all documented in the schema, including the enum meaning. The description only loosely echoes these ('refresh each one's auto-summary note' maps to summarize) and adds no syntax or format detail beyond the schema, so baseline 3 is correct.

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 resource (harness memory hub) and two concrete operations: per-AI-tool memory stats and refreshing each harness's auto-summary note into the shared memory pool. It implies a distinction from the sibling brain_stats (which is presumably global) without naming it 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?

Usage is implied by the two enumerated operations, and 'Unchanged harnesses cost nothing' hints at when summarize is cheap or skippable. However, it never states when to pick this over brain_stats or brain_search, nor any prerequisite for the summarize action.

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 of behavioral disclosure. It clearly discloses idempotency and incremental behavior ('only changed files are re-embedded'), but does not mention potential side effects, configuration dependencies, or what happens if source files are removed. These behaviors would be useful but not critical for calling 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?

The description is two concise sentences with no filler. The key benefit (safe to call repeatedly) and the mechanism (incremental re-index with only changed files) are directly stated, making it very efficient.

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

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

For a tool with one parameter, no output schema, and no annotations, the description provides the key operational facts (what it indexes) and behavioral facts (idempotent, incremental). It doesn't connect to a larger workflow (e.g., 'run before using brain_search'), but the sibling list makes that context implicit. This is sufficient for correct invocation.

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

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

The single parameter 'force' is fully described in the input schema (100% coverage). The description does not otherwise add any meaning to the parameter, so the baseline score of 3 is appropriate, even though the description does not mention it explicitly.

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 ('index') and resource ('configured source directories'), and adds 'incrementally/reindex' to distinguish from the read-only sibling tools like brain_search and brain_stats. An agent can immediately tell this is the ingestion tool.

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

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

The description notes that it is 'safe to call repeatedly', which is a usage hint, but it does not explicitly say when to use the tool verse the siblings or describe any exclusions. The sibling names make the distinction fairly clear, but no direct guidance is given.

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

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

No annotations are provided, so the description carries full transparency burden. It accurately describes a read-only operation that lists links without any side effects. The wording 'based on the current index' implies reading from an existing index, and nothing suggests destructive or modifying behavior, making it fully transparent.

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

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

The description is concise and well-structured: two sentences for behavior and one for usage. There is no redundant information; every sentence contributes to understanding the tool's function and use case.

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

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

Despite having no output schema, the description explains what the tool returns: 'lists every note the given note links to (outbound) and every note that links back to it (inbound)'. This fully covers the expected output, and the parameter is clearly defined, so no critical context 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 schema covers 100% of parameters and describes the single 'note' parameter as 'note name (file stem) to look up'. The description adds no additional semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Show the Obsidian-style [[wikilink]] graph around a note' and explicitly details the behavior as listing outbound and inbound links. This distinguishes it from sibling tools like brain_search or brain_ask, especially with the phrase 'based on the current index'.

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

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

The description provides explicit usage guidance: 'use to explore how a topic connects to others before asking questions, or to find related notes when search keywords fail.' This clarifies when to prefer this tool over alternatives, such as when search fails or before asking questions.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses that the tool writes a markdown note with frontmatter tags, indexes it immediately for same-call searchability, persists across sessions, and shares memories across all MCP hosts mounting loci. This is rich, non-obvious behavior beyond the schema.

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

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

The description is compact and well-structured: purpose first, then behavior, then usage. Every sentence adds distinct value—storage semantics, indexing behavior, persistence/sharing, and explicit usage boundaries—with 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?

Given there is no output schema and no annotations, the description covers all essential operational context: what is written, where it is written, how it is indexed, how long it persists, who can access it, and when to use it. An agent has enough information to invoke the tool correctly without further inference.

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

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

Schema description coverage is 100%, so the schema already clearly documents text, tags, and title. The description adds context about markdown/frontmatter formatting but does not materially expand on the individual parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Store a durable memory (decision, fact, preference, lesson learned) into the shared knowledge base.' It clearly distinguishes this from recall tools by naming brain_search and brain_ask for retrieval, and from ephemeral use by explicitly excluding chit-chat.

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

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

It provides explicit when-to-use guidance ('use for decisions, facts, preferences and lessons worth recording') and when-not-to-use ('do not use for ephemeral chit-chat'). It also names the recall alternatives (brain_search, brain_ask) and explains cross-session, cross-host persistence, giving an agent clear context for 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 provided, the description carries the full burden and does well: it discloses hybrid retrieval, ranked excerpts with file path, heading breadcrumb and similarity score, no LLM call, and the indexed-source limitation. It does not explicitly state the operation is read-only with no side effects, but 'search' plus 'no LLM call' 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?

The description is front-loaded with the core behavior, followed by usage guidance and a concrete limitation. Each sentence earns its place, and the labeled Behavior/Usage structure makes scanning easy.

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

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

Despite having no output schema, the description covers return values (ranked excerpts with file path, breadcrumb, score), key constraints (k limit, indexed sources), and usage context well. Combined with the schema and sibling names, an agent has enough to select and invoke the tool correctly.

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

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

The input schema already documents all four parameters with clear descriptions, so schema coverage is 100%. The description adds context about ranking and results but does not add parameter-level detail beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Search the personal knowledge base') and specifies the retrieval method (hybrid vector + BM25). It clearly distinguishes itself from sibling tools by naming brain_ask as the alternative for synthesized answers.

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

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

Explicitly states when to use this tool: when source material is needed to quote, verify a claim, or see what exists on a topic. It also gives a concrete alternative (brain_ask) and a prerequisite action (brain_ingest) when recent files are missing, leaving no ambiguity about 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?

Discloses behavior beyond basic function: it reads local metadata only and makes no LLM or embedding calls. The returned data is specified, and there is no indication of side effects or hidden costs, making the tool's behavior fully transparent.

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

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

The description is structured with clear sections (Behavior, Reads, Usage) and is concise yet complete. Every sentence adds value, and there is no redundant or vague content.

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

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

Even without an output schema, the description enumerates the exact return fields (path, counts, models, settings) and provides usage context. The tool's purpose, behavior, and expected output are fully understandable from the description alone.

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

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

The input schema is empty and the description explicitly states 'Takes no parameters.' There is no ambiguity about expected inputs, and the schema coverage is complete by virtue of having no parameters.

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

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

The description clearly states the tool reports what the index currently contains and enumerates specific returned metrics (store path, total chunk count, per-file chunk counts, embedding/chat models, retrieval settings). It is unambiguous and easily distinguished from sibling tools that query or modify the index.

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 explicit usage scenarios: call before searching, after ingestion, or when answers seem incomplete. Also notes it reads local metadata only, implying a lightweight, safe alternative to tools that invoke LLM/embeddings.

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

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

The description discloses the full pipeline: retrieves up to k excerpts, synthesizes a structured page, writes to the wiki directory, and indexes immediately. It also mentions the dependency on a working LLM. With no annotations provided, this is strong behavioral disclosure, though it doesn't mention potential side effects like overwriting an existing page.

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

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

The description is compact and front-loaded: it states the core action first, then the behavior, then usage. Every sentence earns its place, and the structure makes it easy for an agent to parse quickly.

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

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

For a tool with 2 params, 100% schema coverage, and no output schema, the description covers the key context: what it does, how it behaves, when to use it, and a prerequisite. It doesn't describe the return value, but with no output schema and a clear write-action, that's a minor gap. The lack of mention of overwriting behavior is a small omission.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds context for k ('how many source excerpts to distill') and topic ('the topic to write the page about'), but these are already in the schema. The description's mention of 'up to k source excerpts' adds a small behavioral nuance, but not enough to push beyond baseline 3.

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

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

The description clearly states the tool's function: generating a wiki page by distilling index knowledge into a curated, cross-linked markdown page. It distinguishes itself from siblings by naming the memory-consolidation layer and the specific output artifact (wiki page), which is unique among the listed brain_* tools.

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

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

The description explicitly says when to use it ('when scattered notes about a topic should become one stable, searchable page') and even covers the regeneration use case ('regenerate the same topic to update it'). It also notes the requirement of a working LLM, which is a clear prerequisite.

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