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

Annotations give destructiveHint=false and idempotentHint=false. The description adds 'append' and 'records' which imply non-destructive, additive behavior. However, it does not disclose details like whether episodes are immutable or what happens on repeated calls with same summary, leaving some uncertainty.

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

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

A single, front-loaded sentence that immediately states the action. Every word is meaningful with no redundancy.

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

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

The description is adequate for a simple append operation but lacks context about return values, error conditions, or further behavioral details. Given no output schema, more elaboration would help 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?

All parameters have schema descriptions (100% coverage), meeting the baseline. The tool description adds no additional meaning beyond the schema explanations, so it does not elevate the score.

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 'append' and resource 'episode to the episodic timeline', clearly stating its action. It distinguishes itself from siblings like 'plur_timeline' and 'plur_episode_to_engram' by focusing on recording a session event.

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

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

No explicit guidance on when to use this tool versus alternatives. Among many siblings, the description does not mention exclusions or contexts where other tools would be more appropriate.

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 annotations only state readOnlyHint=false and idempotentHint=false, but the description discloses side effects and behavior: it resets cached failure state with retry, probes /api/v1/me and decodes token expiry, performs a cross-encoder pass for rerank_eval, and caches verdicts. It also clarifies what the tool does NOT do, avoiding misleading 'healthy' reports. This goes far beyond the annotations.

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 long but every sentence carries valuable information: scope, checks, exclusions, alternatives, and behavioral caveats. It is front-loaded with the core purpose and structured with specific, non-redundant statements.

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

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

Given the tool's complexity (diagnostic, with two optional parameters, no output schema), the description explains what the tool reports, what it probes, what side effects occur, and what it intentionally omits. It is complete enough for an agent to select and invoke it correctly without additional context.

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

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

Schema description coverage is 100%, so per the rubric the baseline is 3. The description does not add parameter-level detail beyond the schema; the schema itself already explains both 'retry' and 'rerank_eval' thoroughly, including cost implications. The description reinforces usage context but does not elevate semantic meaning.

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 starts with 'Diagnose the PLUR ENGINE' and explicitly names the components checked (embedder, hybrid search, remote-store auth), which is a specific verb+resource. It also differentiates from hook/MCP wiring and the CLI 'plur doctor', making the tool's scope unmistakable.

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 clear when-to-use instruction: 'Run this first when recall feels off or team engrams stop syncing.' It also explicitly states what it does NOT check (e.g., .cursor/mcp.json, .cursor/hooks.json, MCP tool count) and directs users to the CLI command for those checks, naming an alternative.

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

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

Annotations provide idempotentHint=false and destructiveHint=false, but the description adds no further behavioral details. It does not disclose side effects (e.g., what happens to the original episode), required permissions, or return behavior. Beyond the annotations, the description is silent on behavior traits.

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 a single, front-loaded sentence that immediately states the action. It is concise (17 words) with no extraneous information, earning its place efficiently.

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

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

Given the tool's complexity (4 parameters, no output schema, no annotations beyond basic hints), the description covers the core purpose but lacks behavioral details and output information. It is adequate but leaves gaps about the promotion process and return value.

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 all four parameters described. The description adds no additional meaning to the parameters beyond what the schema already provides. Per guidelines, baseline score is 3 for high 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?

The description clearly states the action ('Promote an episode to a persistent episodic engram') and the context ('when a session event deserves long-term memory'). It distinguishes from sibling tools like plur_promote by specifying the source (episode) and target (engram) precisely.

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

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

The description provides a basic use case ('useful when a session event deserves long-term memory'), but does not specify when not to use the tool or mention alternatives. Sibling tools like plur_capture and plur_learn could be confused, but no exclusion 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?

Annotations (idempotentHint=false, destructiveHint=false) indicate non-idempotent and non-destructive behavior. Description adds pipeline stages and the need for an LLM endpoint, which are not in annotations. Does not conflict with annotations.

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 concise, front-loaded sentences. First sentence covers action and pipeline; second states requirement. No waste or redundant 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?

Covers purpose and key requirement but lacks context on return values, error scenarios, or how the output is structured. With no output schema, more detail would be helpful for a tool with 7 parameters.

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?

All 7 parameters have descriptions in the input schema (100% coverage). Description does not add any additional parameter meaning beyond what is already 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?

Description clearly states the action (extract meta-engrams), specifies the resource (stored engrams), and outlines the 6-stage pipeline. Tool name and title reinforce this purpose, distinguishing it from siblings like plur_meta_engrams and plur_validate_meta.

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?

Description mentions a prerequisite (LLM API endpoint) but does not specify when to use this tool versus alternatives like plur_meta_engrams or plur_validate_meta. No when-not guidance or explicit 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?

Annotations declare idempotentHint=true and destructiveHint=false, which the description complements by stating 'trains injection relevance over time,' implying a non-destructive learning effect. The description adds behavioral context beyond annotations, but the safety profile is already 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?

The description is a single, front-loaded sentence that conveys the purpose and key feature (single/batch) without waste. Every word 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 no output schema, the description explains the effect (training relevance) but does not mention response format or confirmation. For a simple feedback tool, this is adequate but not complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds the concept of single vs. batch modes, which is already implicit in the parameter structure. The description adds marginal value 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?

The description clearly states the verb 'rate' and the resource 'engram', with the purpose of training injection relevance. It is specific and distinguishes the tool's core function, though it does not explicitly contrast with sibling tools like 'plur_pin' or 'plur_forget'.

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 mentions support for single and batch modes but provides no guidance on when to use this tool over alternatives (e.g., when to provide feedback vs. other actions). No explicit when-to-use or when-not-to-use instructions.

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

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

Annotations provide idempotentHint=true and destructiveHint=true. The description adds valuable context that the operation marks the engram inactive without deleting history, clarifying the nature of the destructiveness. However, it does not disclose potential side effects 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?

The description is a single sentence of 17 words, front-loading the key action and result. Every word adds value, with no redundancy.

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

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

For a simple mutation tool with no output schema, the description covers the essential behavioral outcome (retiring without deletion). It does not specify return values, but given idempotentHint and simplicity, this is a minor gap.

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

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

The input schema already provides descriptions for both parameters ('Exact engram ID to retire' and 'Search term to find engram to retire'), achieving 100% coverage. The description adds no additional meaning beyond the schema, so 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 verb 'retire' and the resource 'engram', with a specific mechanism (by ID or search term). It distinguishes itself from sibling tools (e.g., plur_recall, plur_learn) by focusing on deactivation without deletion.

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

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

The description explains how to use the tool (by ID or search term) but provides no guidance on when to choose one over the other, nor does it mention any prerequisites or scenarios where this tool should be avoided in favor of alternatives.

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

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

Annotations already indicate readOnlyHint and idempotentHint. Description adds value by specifying the nature of events (event-sourced, creation, updates, etc.), which goes beyond the annotations. Does not contradict annotations.

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?

Single sentence, front-loaded with the key action and resource. Every word adds value; no redundancy or fluff.

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 no output schema, the description lists the types of events included (creation, updates, feedback, evolution), which helps the agent understand return content. Lacks details on output structure or pagination, but limit parameter hints at control. Adequate for a read-only history 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 description adds no additional meaning to parameters beyond what schema already provides. Description does not elaborate on limit or engram_id usage beyond implicit filtering.

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?

Description clearly states the tool's purpose: viewing event-sourced history of an engram or all recent history, with specific event types (creation, updates, feedback, evolution). This distinguishes it from sibling tools like plur_recall or plur_learn.

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?

Implies usage for viewing historical events but provides no explicit guidance on when to use vs alternatives, such as plur_timeline. No 'when not to use' or prerequisites mentioned.

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

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

Annotations already indicate non-destructive and non-idempotent behavior. The description adds the key fact of optional auto-saving, but omits details on pattern matching criteria, error handling, or configuration requirements. Minimal added value beyond annotations.

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?

Single sentence, efficient, with no redundant or filler words. Everything contributes to understanding the tool's core function.

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?

Adequate for a simple extraction tool with 5 well-documented parameters, but lacks explanation of what 'engram candidates' are, expected output, or error cases. Missing context compared to the large 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?

Schema coverage is 100%, so the description's role is limited. It highlights 'optionally auto-save' which relates to extract_only, but doesn't enrich parameter meaning beyond the schema descriptions. 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 clearly states the action (extract) and resource (engram candidates) along with method (pattern matching) and optional behavior (auto-save). It distinguishes the tool from siblings like plur_learn or plur_capture by specifying candidates and pattern matching, but lacks explicit sibling 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?

No guidance on when to use this tool vs. alternatives like plur_learn, plur_capture, or plur_inject. The description implies usage for extraction and optional saving, but provides no context or conditions 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?

The description adds value beyond annotations by noting output includes 'directives and considerations' and respects 'token budget'. Annotations already indicate read-only and idempotent behavior, so the bar is lower; this context is helpful.

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 a single, front-loaded sentence that conveys the core purpose and constraints without any superfluous information. Every word 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?

The description explains the tool's purpose but lacks detail about return values (no output schema). Terms like 'scored context injection' and 'directives and considerations' remain vague, leaving room for ambiguity about what exactly is returned.

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?

All three parameters have descriptions in the input schema, achieving 100% coverage. The tool description adds no additional parameter details beyond the general mention of token budget, so 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 gets a scored context injection for a task with token budget constraints. It lacks explicit differentiation from the sibling 'plur_inject_hybrid' tool, though the title hints at BM25 method.

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

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

No guidance is provided on when to use this tool versus alternatives like plur_inject_hybrid, plur_recall, or others. The description does not mention any conditions 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?

The description adds critical behavioral context beyond annotations: it is a hybrid approach that falls back to BM25 if embeddings are unavailable. Annotations already mark it as read-only and idempotent, and the description aligns with no contradiction.

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

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

The description is extremely concise with three short sentences, each adding value: hybrid nature, fallback behavior, and best-default recommendation. No wasted words.

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

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

Given the tool's moderate complexity (3 params, no output schema) and presence of annotations, the description adequately covers behavior, fallback, and recommended usage. Could mention output format but not essential.

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 all parameters described. The description does not add additional parameter-specific details beyond the schema, so 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 explicitly states 'Hybrid injection — BM25 + embeddings for better context selection' with a specific verb and resource. It distinguishes from siblings like plur_inject (simple BM25) and plur_recall_hybrid (hybrid recall) by positioning itself as the default injection method.

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 clearly recommends it as 'Best default for injection', implying preferential use over alternatives. It mentions fallback to BM25, indicating robustness. However, it lacks explicit guidance on when not to use it or direct comparisons to sibling tools.

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

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

Annotations already indicate not idempotent (idempotentHint: false) and not destructive (destructiveHint: false). The description adds value with the multi-agent context but does not elaborate on other behavioral traits such as side effects or rate limits. The description does not contradict annotations.

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 sentences plus a reference, front-loading the main action and then providing critical multi-agent guidance. Every sentence earns its place without redundancy.

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

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

Given the tool's 13 parameters and no output schema, the description covers the core purpose and provides crucial multi-agent context. However, it does not hint at the return value (e.g., engram ID), which is a minor gap. Overall, it is fairly 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% (all 13 parameters have descriptions in the input schema). The description does not add extra meaning 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 clearly states the tool's purpose: 'Create an engram — record a reusable learning, preference, or correction.' It uses a specific verb ('Create') and resource ('engram'), and the multi-agent note provides additional context that distinguishes it from sibling tools like plur_learn_batch.

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 provides when-not-to-use guidance: in a multi-agent orchestration, spawned subagents should not call this tool; instead, they should return findings as text for the parent to persist. It also explains why (tool availability not guaranteed). This is exemplary usage 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?

The description extensively explains dedup pipeline (content-hash NOOP → semantic recall → LLM decision), within-batch dedup, per-item results, non-abort on failure, and LLM call cap. Annotations (idempotentHint=false, destructiveHint=false) are complemented, not contradicted.

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?

Description is front-loaded with purpose and structured well, but slightly lengthy. However, every sentence adds value—no filler. Could be more concise, but given the complexity, it's appropriately detailed.

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 2 parameters, 100% schema coverage, and no output schema, the description covers return values (`ids`, decisions, stats, failures), dedup behavior, failure handling, and usage nuances. It leaves no critical gaps for an agent to invoke 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% (baseline 3). Description adds value by explaining that `engrams` mirrors `plur_learn` fields and clarifying `max_llm_calls` default and behavior. While schema already describes individual fields, the context of batch operation and the LLM call cap are useful beyond 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?

Description clearly states 'Create many engrams in one call' and explicitly positions itself as 'the batch form of plur_learn.' It distinguishes from the single-item sibling and details the dedup pipeline, providing a specific verb+resource+scope.

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 guidance: 'Use this when an orchestration fans out... without N separate calls.' Also warns against using for remote/shared stores ('for shared/remote-store writes prefer plur_learn or pass an explicit local scope'), and explains the max_llm_calls cap for cost control.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that it returns templates and confidence scores, but doesn't disclose additional behavioral traits beyond what annotations and schema imply.

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?

Single sentence with no redundant words; clearly conveys purpose and what is returned.

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 adequately explains return content (structural templates, confidence scores). All 4 optional parameters are described in schema; the description implies filtering but lacks explicit statements about ordering or pagination.

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 each parameter has a description. The tool description does not add additional meaning beyond the schema, baseline 3 applies.

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

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

Description clearly states the tool lists meta-engrams with specific properties (structural templates, confidence scores), distinguishing it from other tools like plur_extract_meta and plur_validate_meta that perform different operations.

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

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

No explicit guidance on when to use this tool vs alternatives; usage is implied by the description but no when-not-to-use or alternative naming.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already convey safety and non-destructiveness. The description adds 'browse' and 'discover', which align with read-only behavior but do not disclose additional traits like result limits, pagination, or data freshness. Since annotations carry the transparency burden, a score of 3 reflects minimal added value.

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?

Single sentence with clear verb 'Browse' upfront. No filler words. Every word earns its place, making it concise and well-structured.

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

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

For a simple browse/search tool with optional parameters and comprehensive annotations, the description is largely sufficient. It lacks output format details (e.g., list of pack names and metadata), but the read-only and open-world hints partially compensate. A small gap exists, so 4 is appropriate.

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 all three parameters described. The description adds no parameter-specific info; it remains generic. Baseline for high coverage is 3, and the description does not exceed it.

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?

Description clearly states the tool browses available packs from the registry, with verbs 'browse' and 'discover'. It implies discovery of new packs, distinguishing from sibling tools like plur_packs_list (likely listing installed packs) and plur_packs_install. However, it does not explicitly differentiate from all siblings, so a 4 is appropriate.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention conditions, exclusions, or refer to sibling tools. The agent receives no help in choosing between plur_packs_discover and similar tools like plur_packs_list or plur_packs_preview.

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

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

Annotations provide non-idempotent and non-destructive hints. Description adds behavioral details: automatic filtering of private engrams, integrity hash generation, default output directory. No contradictions.

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 key action and features. No extraneous information. Every sentence adds value.

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 8 parameters and no output schema, the description covers purpose, default behavior, and filtering. It lacks details on output format or return values, but the tool's name and context make the intent reasonably clear.

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 each parameter has a description. The tool description adds minimal extra meaning beyond the schema (e.g., default output dir). Baseline is 3 for high 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?

The description clearly states the tool exports engrams as a shareable thematic pack with privacy scanning and integrity hash. It distinguishes from sibling tools like plur_packs_install and plur_packs_list by focusing on export functionality.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., plur_packs_preview). It implies it's for exporting packs but doesn't specify contexts such as 'use when you need a shareable package' or 'avoid when you just want to preview'. No exclusions or when-not-to-use advice.

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

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

Annotations (idempotentHint, destructiveHint) are minimal. The description adds valuable behavioral details: mandatory security scan that blocks on secrets, conflict detection, and metadata recording. No contradictions found.

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, no wasted words. First sentence states the core action; second adds critical context (security scan, conflict detection, metadata, and reference to preview tool).

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

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

For a single-parameter install tool with no output schema, the description covers key behaviors (security, conflicts, metadata). Missing return value info or error scenarios, but adequate for the scope.

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

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

Schema coverage is 100% for the single parameter 'source'. The description repeats 'directory path' but adds no new semantic info beyond the schema's parameter description.

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 installs an engram pack from a directory path, with specific actions like security scans and conflict detection. It distinguishes itself from sibling tools like plur_packs_preview and plur_packs_uninstall.

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 advises calling plur_packs_preview first, providing clear usage guidance. It doesn't specify when not to use the tool, but the mention of the prerequisite is strong.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds behavioral context by specifying return fields (integrity hashes, install dates, source paths), which is useful beyond annotations.

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?

Single sentence of 13 words, front-loaded with the key action and resource. No wasted words; every part adds value.

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 covers purpose and return fields. No output schema exists, but the description partially compensates. Could mention pagination or ordering, but not necessary for this simple 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?

No parameters exist, and schema coverage is 100%. The description is not required to elaborate on parameters. A baseline of 4 is appropriate for zero-parameter tools.

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

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

The description clearly states the verb 'List', the resource 'installed engram packs', and specific attributes (integrity hashes, install dates, source paths). It distinguishes from siblings like plur_packs_install and plur_packs_preview.

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

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

The description implies usage for listing installed packs but does not explicitly state when to use vs alternatives like plur_packs_preview or plur_packs_discover. No exclusions or prerequisites mentioned.

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

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

Annotations already declare readOnlyHint and idempotentHint, and description reinforces read-only preview nature, adding detail on what is shown. No contradictions.

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, no wasted words. Information is front-loaded and to the point.

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 simple tool structure (1 param, no output schema), description fully covers purpose, behavior, and usage. Annotations fill the rest.

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?

Single parameter 'source' is well-described in schema with 100% coverage. Description implicitly confirms its use without adding syntax details, which is adequate.

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?

Description clearly states 'Preview a pack before installing' and lists specific outputs (manifest, engram list, security scan, warnings). Distinguishes from sibling plur_packs_install.

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 'Always call this before plur_packs_install' providing clear when-to-use guidance. Could mention when not to use but still strong.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds that uninstalling removes all engrams in the pack, which is consistent and provides useful context beyond annotations. However, it lacks details on reversibility, permissions, or side effects.

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

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

The description is a single, front-loaded sentence that conveys the action, resource, and effect without unnecessary words. Every part 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 the tool's simplicity (one parameter, no output schema, clear annotations), the description is complete. It covers the tool's purpose, the consequence of use, and where to find the required 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?

The single parameter 'name' has schema description 'Pack name to uninstall (use plur_packs_list to see names)'. This adds practical guidance on how to obtain valid input, which goes beyond the schema definition. Schema coverage is 100%.

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

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

The description clearly states the verb 'uninstall' and resource 'engram pack', and the effect 'removes the pack and all its engrams'. It differentiates from sibling tools like plur_packs_install and plur_packs_list through the destructive action, but does not explicitly compare.

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

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

The description provides no guidance on when to use this tool versus alternatives such as plur_packs_preview or plur_packs_export. There is no mention of prerequisites, preconditions, 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?

Discloses behavioral effects beyond annotations: pinned bypasses relevance gate and is persistent. Annotations already indicate idempotent and non-destructive; no contradictions.

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?

Concise and well-structured: opens with purpose, explains significance, then provides usage patterns. No unnecessary words.

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?

Covers all essential behaviors (pin, unpin, list) but lacks explicit description of return values or success indications. Adequate for the tool's simplicity.

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%, but description adds value by explaining the role of each parameter with examples, such as 'Pass {id, pinned:true} to pin'.

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 purpose: 'Toggle the always-load (pinned) flag on an engram.' It explains the concept of pinning and distinguishes from siblings by focusing on this unique 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?

Provides explicit guidance to use sparingly and gives usage examples for pin, unpin, and list. Lacks explicit differentiation from sibling tools, but the unique purpose is clear.

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

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

Annotations indicate read-only and idempotent behavior. The description adds that results are cached for 24 hours, which is a useful behavioral detail. No contradictions with annotations. It could further explain whether generation triggers any side effects, but overall it is 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, consisting of two sentences that front-load the core action. While it lacks structured details like bullet points, the brevity is appropriate for a straightforward 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?

The description is adequate but misses some context given no output schema. It does not explain the format or content of the cognitive profile, which would help agents understand what to expect. For a tool with 5 parameters, additional details about when to use parameters like force_regenerate would improve 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add extra meaning beyond the schema, which is acceptable. 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: to generate or retrieve a cognitive profile synthesized from stored engrams. It uses specific verbs and resource, distinguishing it from siblings like plur_recall or plur_meta_engrams by focusing on a narrative summary.

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

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

The description implies that the tool is for generating/retrieving a cached profile, but it does not explicitly state when to use it over alternatives or provide exclusions. It mentions caching but lacks guidance on when to force regeneration or choose this over similar tools.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds that it activates engrams to appear in injection results, which is consistent and provides some behavioral context, but no additional details about side effects or state changes are given.

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, concise sentence that communicates the core functionality without unnecessary words or structure.

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 tool with no output schema and annotations, the description provides minimal but adequate context. Missing details like what 'candidate' means or idempotent behavior, but annotations compensate partially.

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 descriptions for both parameters ('Single engram ID to promote' and 'Multiple engram IDs to promote'). The tool description does not add further 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?

The description clearly states the verb 'Activate' and the resource 'candidate engrams' with a specific outcome 'appear in injection results'. It vaguely distinguishes from siblings like plur_inject but does not explicitly differentiate from similar tools like plur_pin.

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

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

No guidance on when to use this tool versus alternatives (e.g., plur_inject, plur_pin). The description does not mention prerequisites, conditions, or excluded use cases.

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

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

Discloses important behavioral details beyond annotations, such as scope filtering returning personal-family engrams and the difference between recall and inject behavior. No contradictions with annotations (readOnly, idempotent).

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

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

Two sentences with no wasted words. First sentence front-loads purpose, second provides critical caveats. Efficient and well-structured.

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

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

Given the complexity (6 params, nested objects, no output schema), the description covers key behavioral nuances and usage context. Slightly incomplete regarding return format or pagination, but sufficient for tool selection and invocation.

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

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

Schema coverage is 100% (baseline 3). The description adds significant context for the 'scope' parameter, clarifying its behavior, which goes beyond the schema description. Other parameters not elaborated, but still above baseline.

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 'Query engrams by BM25 keyword matching', specifying the verb, resource, and method. It also distinguishes from the sibling tool plur_recall_hybrid, enhancing clarity.

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 guidance: 'use plur_recall_hybrid for semantic similarity', and details scope behavior nuances, helping the agent decide when to use this tool.

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

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

Annotations already declare readOnly and idempotent. Description adds that it's fully local and uses specific algorithms, adding behavioral context beyond annotations.

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?

Single sentence with no filler. Front-loaded with key purpose. Every part is meaningful.

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 does not explain return values. Schema covers parameters. Lacks details on what the result structure looks like, but annotations reduce that burden. Adequate for a simple search tool.

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

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

Schema coverage is 100%, so parameters are documented. Description does not add extra meaning for parameters, but the algorithmic context helps understand the query parameter. 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?

Clearly states hybrid search using BM25 and local embeddings with RRF, distinguishing it from plausible siblings like plur_recall or plur_similarity_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 calls it 'Best default for most use cases,' guiding the agent to prefer this tool initially. Lacks explicit when-not-to-use but provides positive 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?

Annotations provide idempotentHint=false and destructiveHint=false. The description adds that failure reporting triggers evolution via LLM if configured, and imposes a revision limit, which are important behavioral traits beyond the annotations.

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

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

Three sentences, front-loaded with the core purpose. No wasted words; every sentence adds value.

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, but the description explains the outcome (triggers evolution) and constraints. The tool is simple enough that this is sufficient.

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% with clear parameter descriptions. The tool description adds context about the LLM-triggered evolution, giving extra meaning to the llm_* parameters. This goes beyond the baseline of 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 action (report failure), the target (procedural engram), and the effect (triggers procedure evolution via LLM). It distinguishes from sibling tools like 'plur_feedback' by specifying the procedural engram requirement.

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 specifies that the tool only works on procedural engrams and includes a rate limit (max 3 revisions per procedure per 24h). It does not explicitly state when not to use it or list alternatives, but the context is clear enough for an agent.

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

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

Discloses default read-only behavior, the effect of register:true, and which scopes are auto-registered (shared vs personal). Annotations confirm idempotent but no contradictions. Missing details on auth requirements or response format but adequate.

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?

Five sentences with clear front-loading of purpose. Every sentence adds unique value without redundancy.

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

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

Well-described for a tool with no output schema and two optional params. Explains when to use, effect of params, and which scopes are handled. Could include response format but not required given no output schema.

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

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

Adds significant meaning beyond schema: explains default behavior of url parameter and the effect of register parameter. Schema coverage is 100% but description enriches understanding.

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?

Description clearly states the tool discovers authorized scopes and differences from local registration. It distinguishes from siblings by specifying usage for multiple team scopes.

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 context: 'when you have access to multiple team scopes on one server.' Explains when to use register:true but does not explicitly state when not to use.

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 adds behavioral context beyond annotations by detailing the requirement to supply learnings, which are presumably stored. However, it does not explain side effects of ending the session (e.g., invalidation, cleanup) or clarify the non-destructive nature implied by annotations.

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 moderately concise, starting with the core purpose and then listing extraction categories. While each sentence serves a purpose, the list could be streamlined without losing clarity.

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

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

Given the tool's simplicity (no output schema, few parameters), the description covers the necessary invocation details: how to fill summary and engram_suggestions. It lacks information about return values or session state after ending, but that is arguably inferable.

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

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

The description elaborates on the input schema, providing examples and guidelines for engram_suggestions (object shape with type and statement, bare strings accepted) and summary format (1-3 sentences). This adds value beyond the schema descriptions.

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

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

The description clearly states 'End a session' as the primary action, providing a specific verb and resource. While it does not explicitly differentiate from siblings, the sibling list includes plur_session_start, making the counterpart clear.

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 guidance on when to use the tool: before calling, the agent must review the conversation and extract learnings. It also specifies conditions for including engram_suggestions (at least one if anything learned, empty array rare). No alternative tools are discussed, but none are relevant for ending a session.

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 uses 'inject relevant engrams,' implying a write operation, but annotations declare readOnlyHint=true. This contradiction misleads about the tool's behavioral safety. Additionally, no other behavioral traits (e.g., side effects on persistent state) are 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?

The description is concise at two sentences, with the purpose front-loaded. Every sentence is necessary and 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 session-start tool with 3 parameters and no output schema, the description is too minimal. It lacks details on session lifecycle, idempotency (idempotentHint=false), and interaction with other tools like plur_inject. More context is needed for complete understanding.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning 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 clearly states the tool's action ('Start a session — inject relevant engrams') and the resource ('session'). It distinguishes from siblings like plur_session_end by specifying it is for starting a session, called at the beginning.

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 'Call at the beginning of every session,' providing clear when-to-use guidance. It does not mention exclusions or alternatives, but the context is well-defined by the sibling tool plur_session_end.

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 annotations already declare the tool as read-only and idempotent. The description adds value by explaining the return scores and their interpretation, but this is a natural extension of the output, not additional behavioral traits beyond what annotations provide.

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 with two sentences, front-loading the purpose and usage. Every sentence contributes meaningful information without redundancy.

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

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

Given the low complexity and no output schema, the description adequately explains the return values and their interpretation. However, it could briefly mention the effects of the 'limit' and 'scope' parameters to be more 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% with each parameter described. The description does not add any parameter-specific semantics beyond the schema, which is acceptable given the high coverage. 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 searches engrams by cosine similarity and returns scores. It provides a specific use case (dedup classification) with score thresholds, effectively differentiating it from sibling tools like plur_recall.

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 states the tool is used for dedup classification and gives score thresholds, indicating when it is appropriate. However, it does not specify when not to use it or suggest alternatives among the many sibling tools.

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

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

Annotations already provide readOnlyHint and idempotentHint, so the description does not need to reiterate safety. It adds optional filtering behavior, but does not disclose return format or potential limitations.

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 efficient sentences: first covers main purpose, second adds optional filtering. No wasted words, front-loaded with key information.

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

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

For a simple status tool with no output schema, the description covers core metrics and optional filters adequately. Lacks return format details but is sufficient given tool simplicity.

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 description essentially restates the schema's parameter descriptions. No additional meaning or usage nuance beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Return system health' and lists specific metrics (version, engram count, etc.). It distinguishes itself from sibling tools like plur_learn or plur_recall, which have different functions.

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

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

The description implies usage for system health checks but does not explicitly state when to use this tool over alternatives or when not to use it. The context is clear but not directive.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description confirms idempotency by stating returns 'added' or 'already_registered'. It also explains that remote URLs can host multiple scopes and that each registration is independent, adding context beyond annotations.

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 with two sentences, front-loaded with the core purpose. It efficiently covers both registration types, usage pattern, and return status without unnecessary details.

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

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

Given the absence of an output schema, the description adequately mentions the return status ('added' or 'already_registered'). It covers the 6 parameters sufficiently in context, though more detail on the 'shared' and 'readonly' parameters could be beneficial. Overall, it provides enough information for an agent to use the tool correctly alongside the sibling tools.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the relationship between url+token vs path, and that 'one remote URL can host multiple scopes — call once per team scope'. It also mentions that shared indicates git-committed/team-visible and readonly for purchased packs, enhancing semantics 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?

The description clearly states 'Register an additional engram store' with specific distinction between filesystem (path) and remote (url+token) stores. It also explains that one remote URL can host multiple scopes, differentiating this tool from siblings like plur_stores_list.

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

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

The description provides specific guidance on when to call the tool: 'call once per team scope you are authorized for' for remote URLs. It implies that this tool is for adding new stores, not for listing or other operations. However, it does not explicitly mention when not to use it or compare to other tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's safe. The description adds transparency by specifying that the output includes scope, path, engram count, and conditional metadata. It does not contradict annotations.

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 exceptionally concise with two sentences: the first provides the core purpose, and the second adds conditional detail. Every sentence is informative and without waste.

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

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

Given the tool has no parameters, annotations present, and no output schema, the description sufficiently covers what the tool does and what it returns. It explains the optional inclusion of metadata, which is complete for an agent to decide to use 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 input schema has no parameters (0 parameters, schema coverage 100%), so the baseline is 4. The description does not need to add parameter meaning since none exist.

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 specific verbs ('List') and resources ('configured engram stores') and details the output fields (scope, path, engram count, and optional description/covers). It clearly distinguishes from sibling tools like plur_stores_add (add) and plur_scopes_discover (discover scopes).

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 states the tool lists all configured stores and helps pick the right scope, implying use when you need an overview of stores. It does not explicitly exclude alternatives or state when not to use, but the context is clear given it's the only listing tool for stores.

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

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

Annotations declare readOnlyHint and idempotentHint; description reinforces determinism and no side effects, expands with 'no LLM, no network' and advisory nature. No contradiction.

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 concise sentences, each adding value: purpose, determinism, advisory note, return format. Front-loaded with main purpose.

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?

Explains input usage, behavior, and output format. Lacks detailed candidate structure but sufficient given no output schema.

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

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

With 100% schema coverage, description adds meaning by explaining how parameters are scored (keywords, domain, tags) and that domain is strongest signal, beyond schema descriptions.

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

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

The description clearly states it suggests scopes for an engram ranked by fit, distinguishes from routing tools by stating it's advisory only, and differentiates from siblings like plur_learn.

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 (to determine scope), what it does not do (route or store), and directs to plur_learn for actual storage. Also explains return expectations (empty when nothing matches).

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

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

Annotations already provide idempotentHint and non-destructiveHint. The description adds behavioral detail: git operations (commit, push, pull), repo initialization, and the drop-and-rebuild with full=true, all consistent with annotations.

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 adding value: overall purpose, first vs subsequent calls, and parameter-specific guidance. No wasted words, front-loaded with the core action.

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

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

Given two optional params, no output schema, and good annotations, the description covers main behavior, lifecycle, and recovery. Could mention return values or error cases, but not essential for this tool's 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 100% with descriptions. The description adds a bit of context (e.g., 'recovery path' for full), but does not significantly augment the schema's parameter documentation. 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 clear, specific action: 'Sync engrams via git AND refresh the derived index from YAML.' It names the resource (engrams), mechanism (git), and distinct behavior (index refresh), differentiating from siblings like plur_sync_status.

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

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

Provides explicit guidance: first call initializes repo, remote URL enables cross-device sync, subsequent calls commit/push/pull, and full=true is for recovery. Lacks explicit 'when not to use' or alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint and idempotentHint, indicating safe read-only behavior. The description adds valuable context about the specific status fields (initialized, remote, dirty, ahead/behind), which helps the agent understand the tool's output, though it does not detail other behavioral traits like lack of side effects.

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

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

The description is a single sentence that front-loads the core purpose ('Check git sync status') and efficiently lists the specific checks. Every word adds value, with no redundancy.

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

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

Given the tool has no parameters and no output schema, the description adequately lists the status components returned. However, it does not describe the output format (e.g., string, booleans, counts) which could help the agent better interpret results. Still, it provides sufficient information for basic usage.

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

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

The tool has zero parameters and schema coverage is 100%, so the description does not need to explain parameters. Per instructions, baseline is 4 for no parameters, and the description adds no additional parameter info, which 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 checks git sync status, specifying exactly what aspects are covered: initialization, remote existence, dirty state, and ahead/behind counts. The verb 'Check' and resource 'git sync status' are specific and distinguish this from tools like 'plur_sync' that perform sync actions.

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

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

The description provides no guidance on when to use this tool versus its siblings, such as 'plur_status' or 'plur_sync'. It does not mention any prerequisites, exclusions, or alternatives, leaving the agent to infer context from the name alone.

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?

Describes side effects: scan persists new detections, actions mutate records (confirm, dismiss, resolve). Also mentions env var requirement and temporal discount. Annotations already note non-readOnly and idempotent; description adds concrete mutation details.

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?

Single paragraph of ~150 words, front-loads default behavior. Somewhat dense but each sentence adds value. Could benefit from bullet points or clearer mode separation for 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?

Covers lifecycle and scanning details well, but lacks description of return values/format for list, scan, and actions. With no output schema, the description should indicate what the tool returns to be fully useful.

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%, baseline 3. Description adds value with contextual details (e.g., scan skips recorded pairs, temporal discount ladder). Not all parameters get extra context, but meaningful added explanation beyond schema.

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

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

The description clearly states the tool manages tension lifecycle, with specific modes: listing unresolved tensions, scanning for contradictions, and performing lifecycle actions. It distinguishes from siblings like plur_tensions_purge by covering the full lifecycle.

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 context for when to use each mode (list default, scan with API key, action with id). Implicitly tells when not to use scan without credentials. Could be improved by explicitly stating when to use alternatives, but current guidance is clear.

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

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

Annotations already provide idempotentHint and destructiveHint. The description adds minimal new behavioral context beyond the stated purpose.

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?

Single, well-structured sentence that immediately conveys the action and purpose with no wasted words.

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 simple parameterless tool with adequate annotations. Could mention that it operates on local data only, but not strictly necessary.

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?

No parameters, so baseline 4 applies. Description does not need to explain 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?

Description clearly states the action ('Purge all conflict relations') and the resource ('local engrams'), with additional context ('removes accumulated false positives from the legacy tension-detection system'). This distinguishes it from sibling tools like plur_tensions.

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

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

No explicit when-to-use or when-not-to-use guidance. The function is implied as cleanup for false positives, but alternatives or prerequisites are not mentioned.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, idempotent query. The description echoes 'Query' and 'retrieve', which aligns but adds no new behavioral context (e.g., pagination, data freshness, or scope). With annotations covering safety, a score of 3 is appropriate.

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 a single sentence that front-loads the action ('Query the episodic timeline') and then elaborates on filters. Every word is needed; no fluff. Extremely concise.

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

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

The tool has 5 optional parameters, no output schema, and no nested objects. The description explains the filtering capability but does not mention the output format or any limitations like pagination. Given the lack of output schema, the description could be more complete. However, annotations cover safety, so it's adequate but not full.

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% for all 5 parameters, so the schema already explains each parameter. The description does not add additional semantics or examples beyond what the schema provides. Baseline score of 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 clearly states the tool's purpose: 'Query the episodic timeline — retrieve past episodes filtered by time, agent, or search'. The verb 'Query' and resource 'episodic timeline' are specific. Among sibling tools like plur_recall, plur_history, etc., this tool is uniquely positioned as a timeline filter query, so it distinguishes well.

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

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

The description implies usage for retrieving filtered episodes but does not explicitly state when to use this tool versus alternatives (e.g., plur_recall, plur_history). No guidance on when not to use it or prerequisites. Usage context is hinted but not fully specified.

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

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

Annotations only include idempotentHint=false and destructiveHint=false. The description adds behavioral context by stating it 'updates confidence and domain_coverage', which indicates a mutation. No contradiction with annotations.

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, concise sentence of 13 words communicates the tool's purpose without any redundant or unnecessary 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?

The description is adequate for a simple tool but lacks explanation of the return value, prerequisites (e.g., existence of meta-engram), and any side effects beyond the stated updates. Given no output schema, more detail would help.

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?

Input schema has 100% coverage of parameter descriptions. The description adds no additional parameter-specific details beyond the schema, so 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 clearly states it tests a meta-engram template against engrams from a new domain, using specific verbs and resources. It distinguishes itself from sibling tools like plur_extract_meta (extraction) and plur_meta_engrams (listing) by focusing on validation.

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

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

The description implies usage for validating meta-engrams but provides no explicit guidance on when to use this tool versus its siblings or when not to use it. No alternatives or exclusions are mentioned.

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