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

There are no annotations, so the description carries the behavioral burden. It does disclose that it generates files, requires an interview, does not overwrite unless force is true, and returns setup instructions. It also reveals internal defaults ('everything structural ... is written by the scaffold'). It does not go deeper into side effects such as whether files are created in the current directory, whether the interview is interactive, or whether any external calls occur, but the main behavior is reasonably 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?

Three sentences, front-loaded with the verb and resource, then deliverables, then an important constraint about the interview and overwrite behavior. Every sentence earns its place and no information is wasted.

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

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

For a 7-parameter tool with no output schema, the description covers the core workflow, the interview scope, the generated files, and the overwrite safeguard. It could be more complete by stating where files are written or what 'setup instructions for requested runtimes' looks like, but the essentials an agent needs to act are present.

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

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

Schema description coverage is 100%, so baseline is 3 even without param info in the description. The description adds useful context by grouping the four interview questions (name, agent name, purpose, voice) and clarifying that 'user' is the human's name rather than the agent's. However, it doesn't elaborate on the clients array's exact allowed values or force semantics beyond what the schema already says. This is acceptable but not exceptional.

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

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

The description states a specific verb ('Initialize'), a specific resource ('a new loom identity'), and concrete deliverables (IDENTITY.md, preferences.md, self-model.md). It describes the onboarding-interview source and setup-instruction outputs, and it names a distinguishing behavior relative to siblings (does not overwrite unless force). This is clear and differentiated.

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

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

The description clearly implies when to use this tool: when a new loom identity is needed from scratch, and it explicitly warns the agent not to ask structural questions because the scaffold writes them. It does not explicitly name sibling alternatives for when not to use it, but it gives enough context and constraints for an agent to select it appropriately.

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

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

No annotations are provided, so the description carries full weight. It discloses that the tool returns a third-person brief and includes the push-back mandate, and implies a read-only operation. However, it does not explicitly state side-effect safety or other behavioral constraints beyond what is implied.

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, front-loading the core purpose and key behaviors (third-person framing, push-back mandate). Every sentence adds critical 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?

The description covers the tool's primary function, return content, and important contextual details (push-back mandate, optional addendums, environment overrides). With no output schema, it provides sufficient understanding, though it could be more explicit about output format and effects of all optional 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?

Schema coverage is 100%, so parameters are documented in the schema. The description adds value by explaining how each parameter integrates into the dossier loading process (e.g., role appends a role brief, model and client override environment variables). This goes beyond the schema's basic 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?

Description clearly states the verb 'Load' and the specific resource 'Art's operating brief'. It distinguishes this tool from siblings by specifying it returns standards, taste, and constraints framed for non-Art agents, which is unique among the listed siblings.

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 the tool's purpose: to provide Art's operating brief for worker bodies. It includes a specific behavioral mandate (push-back). However, it does not explicitly state when not to use it or mention alternatives among siblings, leaving some ambiguity.

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

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

With no annotations, the description carries the behavioral disclosure burden and delivers: chronological ordering, oldest-first, no ranking, all-body scope, and boot-time injection. It omits return format/pagination, but for a read-only log query that is a minor gap.

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

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

Two sentences with front-loaded core definition and behavioral traits, followed by practical use cases. The metaphor is slightly ornate but each sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description provides enough to select and invoke it: what it returns, ordering, scope, and typical timing. It lacks explicit alternative routing but is not seriously incomplete.

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 'hours', including default and minimum. The description restates the 'last N hours' concept but adds no new semantic detail 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 identifies a specific resource ('episode tape') and its content: events across all bodies of this identity within a time window, time-ordered oldest-first. It also distinguishes itself from ranked/similarity-based sibling tools by explicitly stating 'never ranked.'

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

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

It provides explicit, practical contexts for use: mid-session catch-up on other sleeves and a nightly indexing pass. It doesn't name alternative tools or state when not to use it, but the usage guidance is clear enough.

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

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

No annotations provided; description adds behavioral context like 'Self is always excluded when ref is given', but does not specify if the operation is read-only or has side effects. Acceptable but could be more thorough.

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 concise sentences, each adding value: purpose, usage context, and parameter distinction. No redundant or irrelevant content.

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

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

Covers main behavior and parameter usage well. No output schema, so return format is not described, but the complexity is moderate and the description is sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions; description adds context that ref and text are alternative anchors and that self is excluded for ref, going beyond the schema's basic 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?

Description clearly states verb 'surface' and resource 'memories semantically near an existing ref or free-form text', distinguishing it from sibling tools like recall or memory_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?

Explicitly recommends use 'during consolidation/dream workflows to find overlap and dedupe candidates', and distinguishes between ref and text anchors. Lacks explicit when-not usage compared to alternatives.

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

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

With no annotations, the description discloses the confirm parameter as a safety gate for bulk deletions, the dry-run preview for non-confirmed bulk requests, and that single-target deletions never need confirm. This provides adequate behavioral context.

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

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

The description is two concise sentences that efficiently convey the tool's purpose, modes, and key parameter behavior. Every part 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?

Despite no output schema or annotations, the description covers all parameter usage patterns, the confirm safety gate, dry-run behavior, and single vs bulk distinction. It fully equips an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds value by explaining the confirm parameter's role, title_pattern as a glob pattern requiring a scope guard, and the grouping of parameters for single vs bulk deletion. This goes beyond basic 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 the tool removes memories and distinguishes between single (by ref or category+title) and bulk (by category/project) deletion. It differentiates from sibling tools like memory_archive or memory_prune by specifying the deletion operation and its modes.

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 when to use single vs bulk deletion and the requirement for confirm in bulk operations, including the dry-run behavior. However, it does not explicitly mention when not to use this tool or suggest alternatives among siblings.

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

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

No annotations provided. Description discloses re-runnable behavior (overwrites manifest), target derivation, and suggested content scope. Lacks details on auth or side effects, but still informative.

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

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

Front-loaded with core action, then usage condition and details. Slightly verbose but well organized.

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 description explains output location and body scope. Adequate for a write tool with two 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?

Schema coverage is 100%. Description adds value by noting frontmatter is stamped automatically for content parameter, and provides default for version. 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?

Clearly states the action: 'write its manifest' at a specific path. Also distinguishes from siblings by focusing on the currently connected harness.

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 call (when identity() reports an onboarding block for unknown runtime) and notes limitation: 'you can only describe yourself, not another harness'.

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

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

With no annotations, the description carries the full behavioral burden and meets it: idempotency, skip-exists default, overwrite semantics, exact loom marker syntax, and re-run behavior for intact vs missing/corrupted blocks are all disclosed. It also clarifies path resolution for the target parameter.

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 information-dense without fluff: first sentence states the core action, second gives the trigger, and a separate paragraph layers the optional target behavior. Every sentence carries actionable detail such as statuses and path rules, and the structure mirrors the tool's two operating modes.

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 main action, optional target behavior, idempotency, marker boundaries, and path syntax, which is sufficient for a moderately complex tool with no output schema. It does not explicitly describe the return value shape or what happens if the target file is absent, but the quoted statuses imply the observable outcomes.

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

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

Schema coverage is 100% and the schema already names parameters well; the description adds meaningful context for target (managed block, markers, re-run behavior, path resolution) and overwrite (default false replaces). It adds less beyond the schema for name, but the overall parameter guidance is solid.

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 uses a specific verb 'Scaffold' with a concrete resource and destination: a harness manifest at <contextDir>/harnesses/<name>.md from the template. It also identifies the triggering condition (identity() reports a missing manifest), which distinguishes the tool from maintaining or describing existing harness state.

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

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

Provides a clear when-to-use trigger: call when identity() reports a missing manifest, and explains the overwrite option for existing manifests. It does not name alternatives or explicitly state when to use update/harness_describe instead, but the invocation condition is unambiguous enough for correct 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?

No annotations provided, so the description carries the burden. It describes the return content (creed, memories, etc.) but does not disclose side effects, idempotency, permissions, or rate limits. It implies a read operation but lacks full behavioral detail.

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 with no fluff, front-loaded with purpose, and includes an imperative callout. Every sentence is meaningful and 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 description explains what the tool does, when to use it (first), and what it returns. Lacks output structure details but is otherwise complete given the tool's complexity and the presence of sibling tools for identity management.

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 having a description. The tool description adds context about the purpose but does not enhance parameter semantics 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 loads persistent identity and returns creed, memories, preferences, and self-model. It distinguishes itself from sibling tools like 'update_identity' by emphasizing it should be called first.

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 instructs 'Call this tool FIRST before doing any other work', providing clear usage context. Does not mention alternatives or when not to use, but the 'first' directive is strong guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses key behavioral traits: archived pages are excluded from certain tools (knowledge_recall and knowledge_maintain), remain in the database, and are recoverable via knowledge_restore. This goes beyond a simple description and provides actionable transparency.

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

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

Two sentences: the first defines the action and effect, the second provides usage context and alternatives. Every sentence adds value, no filler. 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 the tool's complexity (2 parameters, no output schema), the description is complete enough. It explains the effect, availability, and recovery. However, it doesn't detail the status change or any side effects, but the context of sibling tools makes it 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 coverage is 100%, so baseline is 3. The description adds context by referring to the 'note' as a 'tombstone note' and explaining the purpose of both parameters ('slug' as the page to archive, 'note' as why it's being retired), reinforcing the schema descriptions without adding significant new details.

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: 'Soft-retire a knowledge page: set its status to archived with an optional tombstone note.' It distinguishes itself from deletion and the sibling tool knowledge_supersede, providing a specific verb and resource.

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

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

The description explicitly advises when to use this tool ('Use this instead of deletion when the page may need to be audited or recovered') and when to prefer an alternative ('For deduplication merges, prefer knowledge_supersede'). This provides clear usage guidelines.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It explains that replace-writes snapshot the displaced body into page_revisions (capped) and that restore snapshots first, making it non-destructive. It does not cover error handling, auth requirements, or rate limits but provides sufficient insight for safe usage.

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 three sentences that front-load the core purpose and efficiently explain all modes. No extraneous information; every sentence earns its place.

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

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

The description covers the main functionality but lacks details on output format for listing (what metadata?) and reading (body format?). It also does not specify the result of a restore operation. Given no output schema, more detail 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 coverage is 100%, so parameters are documented. The description adds value by explaining the three usage modes, how parameters combine (e.g., restore requires revision_id), and the behavior of each combination. This goes 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 it is for 'Body-revision history for a knowledge page' and details three distinct modes: listing snapshots, reading a snapshot, and restoring. It effectively distinguishes from sibling tools by focusing on revision history and recovery.

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 when to use each mode: slug alone for listing, slug+revision_id for reading, and adding restore:true for restoration. It also notes that restore is never destructive, providing guidance. However, it does not explicitly contrast with alternative tools or specify when not to use this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only,' which is a critical safety trait for an agent, and it explains nuanced classification behavior such as which items count as misfiles and which are correctly placed. It does not discuss auth or rate limits, but the main behavioral surface of a read-only audit is well covered.

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

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

The description is front-loaded with the essential 'Read-only health report' framing and then uses a compact three-branch structure. Every clause earns its place, including the important misfile nuance, and there is no filler or repetition.

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

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

For a tool with no output schema and no annotations, the description provides strong contextual coverage: purpose, read-only safety, branch criteria, interpretation guidance, and a follow-up workflow via knowledge_write. It stops short of 5 because it does not describe the response/return shape or how results are presented to the agent.

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 baseline is 3. The description reinforces the meaning of thresholds by tying them to branches ('thin body + high hit_count', 'not accessed recently'), but it adds no parameter-level detail beyond what the schema already provides. It does not elevate above the 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 opens with a specific verb and resource: 'Read-only health report for the knowledge store.' It then enumerates three concrete report branches, making the tool's purpose unmistakable and distinguishing it from write, recall, and maintenance siblings. Naming knowledge_write as the action counterpart further clarifies the division of responsibility.

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 implies when to use the tool: whenever a knowledge-store health report is needed, and it explicitly instructs to pair with knowledge_write to act on findings. However, it does not give explicit 'when not to use' guidance or differentiate from related audit/recall siblings such as memory_audit or knowledge_recall.

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?

Despite no annotations, the description fully discloses behavioral traits: re-parenting, deduplication, MAX(verified_at), archiving losers with tombstone, loser bodies returned, and effects of each parameter like hard_delete_losers and append_loser_bodies.

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

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

Front-loaded with core action, then details of behavior, then usage guidance. Every sentence adds value without redundancy. 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 5 parameters, no output schema, and high complexity, the description covers all essential aspects: what happens to source pages, return values (loser bodies), parameter effects, and distinguishes from siblings. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema, such as deduplication logic and the curator workflow for append_loser_bodies, but the schema descriptions themselves are already fairly detailed.

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

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

The description states 'Consolidate 2+ knowledge pages into one canonical page' with specific verb and resource. It distinguishes from sibling tools knowledge_supersede and knowledge_write explicitly.

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

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

Provides explicit when-to-use: 'Use knowledge_write first if the target body needs updating before merging.' Also contrasts with knowledge_supersede, telling user to use merge when consolidating data from multiple pages.

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

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

With no annotations, the description carries full burden. It discloses key behaviors: preservation of citations/verification, supersessions pointer (unless leave_pointer=false), atomic batch operations with rollback, and collision rejection. Missing details on old slug accessibility after move and return value, but overall 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 well-structured with bullet points for modes, front-loaded with the main action. It is slightly verbose but every sentence adds value. No 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?

Given no output schema, the description does not explain what the tool returns (e.g., success message, updated page info). It also omits potential restrictions on re-domain (e.g., destination domain existence) and reversibility. However, it covers modes, constraints, and alternatives adequately for typical use.

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 baseline is 3. The description adds significant value by explaining modes, parameter relationships (e.g., from_domain_prefix requires to_domain_prefix), constraints (collision -> use knowledge_merge), and atomic behavior, going well 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 the tool re-keys or re-domains a knowledge page in place, preserving citations and verification history. It distinguishes three modes (single-page, batch by slug list, batch by domain prefix) and explicitly contrasts with knowledge_merge for collision scenarios.

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 each mode, including prerequisites (e.g., new_domain required for batch-by-slugs, from_domain_prefix requires to_domain_prefix) and alternatives (use knowledge_merge when new_slug collides). This helps the agent choose the correct tool and mode.

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

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

No annotations provided, but description fully covers irreversible deletion, citation cascade, confirm required, batch rejection for mixed archives, and that supersession pointers are preserved.

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 covering all necessary points without redundancy. It is front-loaded with action and guard, but slightly dense; could be split into more sentences for easier parsing.

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

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

For a two-parameter tool with no output schema and no annotations, the description completely covers preconditions, behavior, safety, side effects, and use cases. No gaps.

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

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

Schema coverage is 100%, but description adds meaning: explains the archive guard for slugs, mixed list behavior, and that confirm must be explicitly true as a safety gate. Slightly redundant with schema but adds useful context.

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 'Hard-delete[s] one or more archived knowledge pages and cascade[s] their citations.' It uses a specific verb and resource, and distinguishes from siblings like knowledge_archive (archive first) and knowledge_restore.

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: 'clean up tombstoned cruft after merge/supersede workflows' and when not: 'not for retiring active pages.' It also provides a guard and advises calling knowledge_archive first.

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

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

With no annotations, the description fully discloses behavior: archived pages are never surfaced, full detail stamps access/hit counts, output size-guarding causes overflow to index entries, and recall by slug to read full pages. Sort_by_verified behavior is also described.

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 dense paragraph but is front-loaded with the main purpose. Every sentence adds value, though it could be more structured (e.g., separate sentences for each tier). Still efficient and clear.

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 6 parameters, no output schema, and no annotations, the description covers all essential behavioral details, edge cases (size-guarding, defaults, slug precedence), and parameter interactions. It is complete for an agent to use 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% with descriptions for all 6 parameters. The description adds meaning beyond schema by explaining interactions (slug precedence, query vs browse, detail defaults, size-guarding logic, sort_by_verified timestamp behavior). This compensates fully.

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 the knowledge store using LIKE matching and slug lookup. It distinguishes between query-based search and exact-slug fetch, and explains the two detail tiers, making the purpose specific and differentiating from siblings like 'recall' or 'find_similar'.

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 on when to use slug over query ('Prefer slug over query when you know the page'), explains the default detail tier based on query presence, and describes the size-guarding behavior. This helps the agent choose correctly.

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

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

With no annotations, the description fully bears the burden of disclosure. It reveals side effects: 'Clears the archive flag and tombstone note. The page becomes visible to knowledge_recall and knowledge_maintain again.' This provides useful behavioral context beyond the basic action.

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, direct, and front-loaded with purpose. Every sentence adds value with no 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?

For a simple restore tool with one required parameter and no output schema, the description is complete. It explains the action, what is cleared, and the effect on visibility, leaving no critical gaps.

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

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

The input schema has 100% coverage with a clear description for the only parameter (slug). The tool description does not add extra meaning beyond what the schema provides, 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 clearly states the tool's purpose: 'Restore a previously archived knowledge page back to active status.' The verb 'restore' and resource 'knowledge page' are specific, and it naturally distinguishes from siblings like knowledge_archive (archive) and knowledge_purge (delete).

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 when to use the tool (when you need to unarchive a page) but does not explicitly state when not to use it or compare with alternatives like knowledge_recall for active pages. Usage context is clear but not comprehensive.

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

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

No annotations provided, so the description carries full burden. It discloses that old_slug is archived with a tombstone pointing to new_slug, and that a supersession relationship is recorded. It does not contradict annotations. Could mention reversibility or permission requirements, but overall good.

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 main action, followed by workflow and precondition. Every sentence adds value with no superfluous 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 no output schema, the description explains the effects: archiving, tombstone creation, and recording relationship. It also covers prerequisites and workflow. For a merge primitive with side effects, this is 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 parameters described). The description adds meaning beyond the schema by clarifying roles: old_slug is the 'loser' and new_slug is 'canonical'. It also explains that note is optional and reinforces the purpose of each parameter.

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 marks a page as superseded, archives the old page, and records the relationship. It uses specific verbs and resources, distinguishing it from siblings like knowledge_merge and knowledge_write.

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 the workflow: first write the canonical page with knowledge_write, then call knowledge_supersede. It also specifies the precondition that both pages must exist. However, it does not explicitly state when not to use this tool or list alternative tools for different scenarios.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool sets verified_at and optionally freshness_anchor, and an optional note appends a dated section to the body (append-only). It also mentions rejection behaviors. However, it omits details like idempotency or authentication requirements, though these are minor.

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 four concise sentences, front-loading the core action ('Stamp a knowledge page as verified WITHOUT touching its body') and logically separating modes and constraints. Every sentence adds value, and there is no redundancy or filler.

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

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

Given 5 parameters, no output schema, and no annotations, the description covers the tool's behavior well: it explains modes, constraints, and rejection conditions. However, it does not explicitly describe the return value on success (e.g., confirmation or timestamps), which would add completeness for an agent.

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 baseline is 3. The description adds significant meaning beyond the schema: it explains the two modes, mutual exclusivity of slug and slugs, the effect of note appending ('Never replaces the body'), and that freshness_anchor is preserved when omitted. This enriches parameter 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?

The description clearly states the tool's action: 'Stamp a knowledge page as verified WITHOUT touching its body' and explicitly distinguishes it from sibling tools like knowledge_write by recommending 'use it (never knowledge_write) to record claims still hold'. It covers both single-page and batch modes, leaving no ambiguity about the resource or verb.

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 this tool versus alternatives ('never knowledge_write'), explains the two modes (single vs batch) with mutual exclusivity, and lists constraints such as rejection of archived pages and failure of batch on unknown slugs. This is comprehensive and actionable.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses that body REPLACES by default, that 'append' adds instead, that citations are always appended with exact-duplicate dedup, and that re-sending is safe. It also explains the epistemic gate outcomes (provisional/internal/sourced), which is essential behavioral context beyond the bare schema.

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

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

The description is dense but well-structured: a one-line summary, then class definitions, then behavioral details broken into bullets. It is longer than average, but the epistemic-gate and domain-classification details are load-bearing for correct invocation and not fluff. The §E1 reference is slightly cryptic, but it does not undermine 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?

For a complex 9-parameter upsert tool with no annotations and no output schema, the description covers the critical invocation concerns: slug-based upsert behavior, body combine modes, citation dedup, epistemic statuses, class selection, and filing test. An agent has enough context to choose the right domain and citation source_kind values and to understand the consequences of re-sending.

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 baseline is 3. The description adds meaningful semantics beyond the schema by explaining the domain classification (world/ vs ours/), the epistemic meaning of citation source_kind combinations, and the practical effect of mode. This enriches the parameters even though the schema already documents each field.

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

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

The description opens with a specific verb and resource: 'Upsert a knowledge page by slug', and clarifies the two classes (world/ vs ours/) with concrete examples. It does not explicitly distinguish this tool from sibling tools like knowledge_merge or knowledge_supersede, so it stops short of full 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?

The description gives clear context on when to use the world/ class versus the ours/ class, including the 'World filing test' and domain naming rules. It does not explicitly mention when not to use this tool or name alternative siblings, so it lacks the full when/when-not guidance.

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

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

No annotations exist; the description fully discloses the behavior: creates a tombstone, excludes archived memories from certain operations, and specifies recoverability via memory_restore. 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 with no wasted words. Front-loaded with the verb and resource, then provides usage guidelines and behavioral details 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?

Despite lacking output schema, the description covers the operation's purpose, constraints (exclusion from recall/list/audit/find_similar), recovery path, and usage context. No critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for 'note' as a tombstone note but does not elaborate on ref, title, or category beyond the schema. Adequate but does not significantly enhance parameter 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 states a specific action ('soft-retire a memory'), targets a clear resource ('memory'), and uses a verb ('archive') that distinguishes it from 'forget' and 'memory_restore'. It also clarifies the outcome: moved to archive tier with a tombstone.

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

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

Explicitly states when to use this tool ('Use this instead of forget when the memory may need to be recovered or audited later') and contrasts with sibling tools like recall, list, audit, and find_similar, which exclude archived memories.

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

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

No annotations provided, so description carries full burden. It states it is read-only, which is the key behavioral trait. It does not mention performance, size of return, or other potential effects, but for a read-only report, the disclosure is sufficient.

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 succinct sentences: first defines purpose, second provides usage guidance. No redundant words, highly 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?

Describes the output contents (totals, category breakdown, stale memories, etc.) and mentions defaults for parameters. Lacks output schema, but the description gives enough context for an agent to understand what the tool returns. Could mention the format but not critical.

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 having a description. The tool description does not add additional meaning beyond what the schema already provides (e.g., default values, thresholds). 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?

Description clearly states it produces a one-shot health report for the memory store, listing specific components (totals, category breakdown, stale memories, near-duplicate pairs, expired refs). It distinguishes itself from siblings like `forget` and `update` by being read-only and diagnostic.

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 'Read-only — pair with `forget`/`update` to act on findings.' This tells the agent when to use this tool (to inspect) and when to use alternatives (for acting on findings), providing clear context.

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

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

No annotations provided, so the description carries full burden. It mentions listing with filters but does not describe pagination, ordering, or return structure. Adequate but missing some 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?

Two sentences, front-loaded with the core purpose. Every word adds value. 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 covers purpose and use cases but does not explain output format, default behavior (e.g., limit default), or pagination. Adequate for a simple list tool but could 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%, so baseline is 3. The description echoes the schema's filter parameters without adding significant new meaning. Acceptable but not enhanced.

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 lists memories without semantic search, with optional project/category filters. It distinguishes itself from semantic search tools like 'recall' or 'find_similar'.

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 use cases (auditing, maintenance, discovery) and implies when not to use (when semantic search is needed). It doesn't explicitly name alternative tools 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?

With no annotations, the description covers key behaviors: lists drafts, not actual memory, excluded from certain operations, and ordered newest first. It does not mention rate limits or permissions, but for a read-only list, this is 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?

The description is two sentences. The first sentence states the core purpose, and the second adds essential context and next steps. Every sentence 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?

The description fully covers what the tool returns (list of proposals), ordering, the nature of the data, and links to follow-up actions. Given no parameters or output schema, it provides sufficient context for an agent to use correctly.

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

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

The input schema has no parameters, so the description does not need to add parameter details. The baseline for zero parameters is 4, and the description appropriately omits any parameter information.

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 lists all pending proposals from the capture-propose queue, ordered newest first. It distinguishes itself from sibling tools like memory_list and recall by specifying that these are drafts and not part of memory.

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 clear context about what the tool does and references related actions (ratify/reject). It implies usage for reviewing drafts but lacks explicit when/when-not guidance; however, the distinction from other memory tools is evident.

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

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

With no annotations provided, the description carries the full burden and discloses important behavior: proposals are invisible to recall, memory_list, find_similar, and the boot digest; validation is deferred to ratify time; and drafts may be rough. This gives the agent an accurate model of the tool's side effects and lifecycle.

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

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

Three sentences, each earning its place: the core staging action, the key invisibility behavior, and the intended usage scenario. The most decision-relevant information is front-loaded.

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

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

For a tool with 7 parameters, no output schema, and no annotations, the description provides sufficient behavioral and lifecycle context. The distinction between proposed and ratified memory is fully explained, and the deferred validation note covers the most important edge consideration.

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 every parameter. The description adds contextual value around the proposal workflow but does not need to repeat parameter meanings; the 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 uses a specific verb and resource — 'Stage a DRAFT memory in the capture-propose queue' — and clearly distinguishes proposals from authored memories by listing what they are invisible to. This lets an agent immediately tell it apart from memory_ratify, memory_reject, and similar tools.

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

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

It explicitly states when to use the tool: when a background lane wants to suggest a write without committing it, leaving ratification to a human or Art. It does not name the alternative tools for direct memory creation, but the contrast with ratified/canon memory is clear enough to guide tool selection.

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

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

Discloses that the tool is destructive (removes) and offers a safe preview via dry_run. With no annotations, the description carries the burden and does so adequately, though it could mention permanence or auth requirements.

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

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

Two concise sentences that are front-loaded and to the point. 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 the core functionality and safe usage pattern. Lacks details on return values or post-deletion state, but given the simplicity of the tool and lack of output schema, it is reasonably 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 covers 100% of parameters and the description adds value by explaining the purpose of dry_run (preview without deleting) and the meaning of stale_days (days since last access).

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 the action (remove), the resource (expired memories), and the condition (TTL elapsed). The alternative dry_run mode is also mentioned, differentiating it from other tools.

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

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

Provides guidance on using dry_run for preview, but does not explicitly contrast with sibling tools like forget or knowledge_purge. However, the context is clear enough for typical 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?

No annotations are present, so the description carries the full burden—and it delivers. It discloses side effects: the proposal is loaded, overrides applied, committed through the same validated path as remember, invalid proposals stay pending with a typed reason, and successful ratification removes the proposal from the queue and makes the memory recallable.

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, then behavior, then significance. Every sentence contributes: the first says what it does, the second explains mechanics and failure handling, the third communicates its critical role.

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 six parameters and no output schema or annotations, the description covers the essential workflow, success conditions, failure behavior, and side effects. It is slightly light on what the tool returns on success and on edge cases like a nonexistent id, but the core information needed to call it correctly is present.

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

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

Input schema coverage is 100%, with each parameter already described as an override or the proposal id. The description adds the helpful framing that the optional fields are 'your edits on accept,' but it does not add significant meaning beyond what the schema already states.

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

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

States a specific verb and resource: 'Ratify a pending proposal into a REAL memory.' It also establishes the tool's unique role as 'the gate' between proposal and canonical memory, clearly distinguishing it from memory_propose, memory_proposals, and memory_reject.

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?

Clearly implies when to use it: when a pending proposal has been reviewed and should become a real memory. It does not explicitly list alternatives like memory_reject for refusals, but the workflow context is unmistakable and the 'gate' statement reinforces its place in the proposal lifecycle.

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

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

With no annotations, the description takes full responsibility, disclosing that the tool deletes the staging row and does not write memory. This is sufficient for a simple rejection, though it could mention irreversibility or error cases.

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 sentences, front-loaded with the key action, 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?

For a simple tool with one parameter and no output schema, the description provides adequate context: purpose, usage, and behavioral effect. Slightly lacking in error examples but overall complete.

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

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

The sole parameter 'id' is described in the schema as 'Proposal id (from memory_proposals)', and the description does not add further semantics beyond that. Given 100% schema coverage, 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 verb 'discard' and the specific resource 'pending proposal'. It distinguishes from siblings like memory_ratify by noting that no memory is written and the staging row is deleted.

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 'Use this for drafts that should not become canon', providing clear context and differentiation from committing actions like memory_ratify.

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

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

No annotations provided, so description fully carries the burden. Discloses clear behavioral traits: clears archive flag and tombstone note, restores visibility to multiple operations. Lacks details on permissions or error handling, but sufficient for simple mutation.

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

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

Two sentences, zero waste. Front-loaded with action and clear effects. 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 description explains return effect adequately. Covers what happens when restored. Could mention what happens if memory is not archived or if ref is invalid, but overall complete for a simple 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%, all parameters have descriptions. Description adds no additional meaning beyond schema. Does not explain which parameter combination is required (ref vs title+category) or constraints.

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

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

Description clearly states verb 'Restore' and resource 'previously archived memory to active set'. Distinguishes from sibling tools like memory_archive (archive) and knowledge_restore (different resource). Provides specific actions: clears archive flag and tombstone, makes visible to recall/list/audit/find_similar.

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?

Implied usage: use for restoring previously archived memories. No explicit when/when-not or alternatives. Could mention that it only works on archived memories and that the opposite is memory_archive.

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

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

With no annotations, the description carries the behavioral burden. It discloses the MMR diversity reranking, the default lambda, that the top result remains the most relevant, and how to request pure relevance ordering. This is meaningful behavioral detail beyond a simple 'retrieve memories' statement.

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

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

The description is compact and front-loaded with the core purpose, followed by usage context and the key algorithmic nuance. Every sentence contributes information that helps an agent decide and invoke correctly, 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?

The description covers the operation, the data source, when to use it, and the diversity behavior, while the schema fully documents all parameters. It does not explicitly describe the return format or contrast with siblings like knowledge_recall or find_similar, but this is not critical for a straightforward retrieval tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantic value specifically for the diversity parameter, explaining the MMR behavior and the effect of passing 0, which goes beyond the schema's formula. Other parameters are adequately covered by 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 verb 'Retrieve' clearly identifies this as a read operation, and the resource 'memories relevant to a query or topic' is specific. It is easy to distinguish from siblings like remember (write) or memory_list (listing) because the description focuses on query-based retrieval from past sessions.

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 'Use this when you need context from past sessions,' giving a clear trigger condition. It does not name alternatives or provide explicit when-not-to-use guidance, but the usage context is strong enough to guide 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?

No annotations are provided, so the description carries the behavior disclosure burden. It explicitly discloses the key trait of cross-session persistence, which is valuable. However, it does not mention return behavior, expiration nuances, idempotency, or that some categories like 'episode' have a short default TTL that may not persist as the blanket statement implies.

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 filler; the core action and persistence guarantee are front-loaded. Every clause earns its place and the where-to-use guidance immediately follows the 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?

The tool has moderate complexity with six parameters, a nested metadata object, an enum, and no output schema. The description is adequate for initial selection, but it does not explain how this tool relates to update, forget, recall, or memory_list, and it gives no hint about the returned value or created memory identifier.

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 parameters are already well-documented in the schema itself, establishing a baseline of 3. The description adds some semantic context about 'important' information and future-session availability, but does not meaningfully enrich individual parameter meaning beyond the schema.

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

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

States a specific action ('Store') and resource ('episodic memory' that persists across sessions), making it clear this is the create/write memory tool. It distinguishes itself from read-oriented siblings like recall and memory_list, though it does not explicitly name any sibling alternatives.

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 clear trigger conditions: use when learning something important about the user, project, or self that should be available in future sessions. It gives good context for when to invoke the tool, but does not state when not to use it or contrast it with update, forget, or other memory mutation tools.

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

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

With no annotations, the description must fully disclose behavior. It mentions updating content and metadata but does not specify side effects, authorization requirements, or whether the operation is idempotent. More detail would improve transparency.

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

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

The description is two sentences, each providing essential information without redundancy. It is concise and front-loaded, making it easy to read.

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

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

The tool has no output schema, and the description does not mention what the tool returns (e.g., success indicator, updated memory object). Given the complexity and number of parameters, the description could be more complete by indicating the 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?

The input schema has 100% description coverage, so the schema already explains parameters well. The description adds value by clarifying how to find the memory and what operations are possible (replace content, update metadata, or both), which is beyond the raw 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 the tool updates an existing memory, specifies how to find it (by ref or category+title), and what can be updated (content, metadata, or both). This distinguishes it from siblings like 'remember' (create) and 'forget' (delete).

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 guidance on how to identify the memory to update (by ref or category+title), which is helpful. However, it does not explicitly state when not to use this tool or compare with other update-like siblings such as 'knowledge_merge' or 'memory_ratify'.

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

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

No annotations provided, so description carries burden. It discloses listing behavior when parameters omitted and immutability of IDENTITY.md. Lacks detail on destructive effects, auth requirements, or rate limits, but such might be implicit.

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

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

Three sentences, front-loaded with purpose, then targeting detail, then usage tip. Every sentence adds value 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?

Given 4 parameters, no output schema, and no annotations, the description covers purpose, usage, and parameter behavior. Immutability note adds completeness. Could mention response 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%; description adds context: 'Call without section/content to list' and 'Targets H2 sections', which clarifies parameter usage 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?

Clearly states it updates self-model or preferences with section-level precision, distinguishing it from siblings like the generic 'update' tool. The verb 'update' and resource 'identity files' are specific.

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

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

Provides explicit guidance: call without section/content to list sections, and notes IDENTITY.md is immutable. Missing explicit when-not-to-use compared to alternatives, but context from sibling tools and description is sufficient.

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