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

With no annotations, the description carries the transparency burden. It explains the tool displays an overview and instructs the agent to relay it, which is adequate for a simple help tool. It doesn't hide any side effects or limitations, though it could mention whether it's purely informational.

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 tool's purpose, then usage guidance. Every word earns its place with no redundancy.

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

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

For a zero-parameter help tool with no output schema, the description fully covers what it does, what content it includes, and when to invoke it. The instruction to relay the overview closes the loop for 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?

There are zero parameters, so the baseline is 4. Schema coverage is 100% trivially, and no parameter explanation is needed. The description correctly focuses on use case rather than parameter 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 states a specific verb 'Show' and resource 'what aidimag offers,' enumerating tools, prompts, resources, and dim CLI commands. This clearly distinguishes it from sibling tools which handle memory, scratchpad, tickets, etc.

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 call: when the user asks what aidimag can do, how to use it, or types 'aidimag help.' It also instructs to relay the overview, giving clear operational guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses key behaviors: facts are 'queued for human review' (not immediately stored), secrets are 'redacted server-side before any LLM sees the text,' and it works across multiple IDEs/agents. It stops short of describing response formats or potential errors, but covers the most critical traits.

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

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

The description is front-loaded with the core action, followed by context, timing, security, and alternatives. It is slightly redundant (e.g., 'tool-agnostic' and 'Works from ANY IDE/agent' both make the same point) and contains jargon ('dim harvest') that may be unfamiliar, but it remains efficient and avoids 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 tool with no output schema and only three parameters, the description covers the essential context: what it does, when to use it, how it handles sensitive data, and how it differs from alternatives. It does not describe the exact response shape, but the lack of output schema makes that less 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 description coverage is 100%, so baseline is 3. The description reinforces the main parameter ('pass the messages the USER typed this session (verbatim)'), but this largely repeats the schema's existing parameter descriptions. It does not meaningfully add semantics beyond what the schema already provides.

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

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

The description clearly states the tool's function: harvest the current chat session by passing user messages verbatim to extract durable facts for human review. It explicitly differentiates itself from siblings by positioning as 'the live, tool-agnostic equivalent of dim harvest' and by recommending context_note for single facts.

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: 'Call at session end, or after a long exchange rich in project knowledge.' It also names an alternative for a specific use case: 'For single facts stated in passing, prefer context_note instead.' This gives the agent clear decision criteria.

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. It reveals that the tool queues proposals for `dim review` and never writes directly, disclosing the output behavior and safety profile. It also implies incremental scanning by default via the 'full=true' option, which is important behavioral context. It doesn't detail potential failure modes, but schema covers prerequisites like LLM availability.

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

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

The description is three short sentences, each conveying distinct information: purpose, behavioral implication, and usage guidance. It is front-loaded and free of redundant content, making it 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?

The tool is well-covered: purpose, usage, and key behavioral constraints are present. There is no output schema, but the description explains the queue-based output mechanism. The only gap is that it doesn't specify what happens to queued proposals or how to retrieve them, but the sibling tool `proposals_pending` likely covers that. Overall, adequately 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 description coverage is 100%, so the schema already documents each parameter's meaning. The description reinforces the `full` parameter's purpose when it mentions 'full=true to rescan all history,' adding usage context. It doesn't add syntactic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool mines git commit history for memory-worthy candidates, which is a specific action on a specific resource. It distinguishes itself from sibling tools by clarifying it queues proposals rather than writing directly. The reference to `dim mine` provides an additional clear context.

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 after meaningful commits, or with full=true to rescan all history,' giving clear when-to-use guidance. It also states it never writes active memory directly, implying that memory_write should be used for that purpose, thus providing an implicit alternative. This is strong usage guidance.

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

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

With no annotations provided, the description takes on full disclosure duty. It reveals that facts are 'queued for review with high trust' and labels the evidence as HUMAN_ATTESTED, giving the agent a clear picture of what happens post-call. It doesn't mention other side effects, but for a capture-like tool this level of transparency is strong.

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 appropriately dense and well-front-loaded with the core action. Every sentence serves a purpose—purpose, timing, triggers, exclusions, and outcome. It loses a point for minor redundancy ('Call this IMMEDIATELY' and 'don't wait for session end' are somewhat repetitive), but overall it remains efficient.

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

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

For a simple capture tool, the description covers all necessary aspects: what to capture, when to capture, when to skip, and what happens after. The schema's rich property descriptions fill in the rest. A minor gap is not explicitly stating what should happen if multiple facts appear at once, but that's not critical for correct invocation.

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

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

Despite 100% schema coverage providing a solid baseline, the description adds substantial value by mapping natural language triggers to enum values ('we always X' → CONVENTION) and offering a concrete example for the `statement` field. This goes well beyond what the schema alone provides, making the trigger logic and statement formulation unambiguous.

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 a specific verb+resource: 'Capture a durable fact the USER just stated in chat.' It distinguishes itself from sibling memory tools by scoping to user-stated codebase knowledge. The inclusion of concrete trigger phrases ('we use X because Y', 'never do X') makes the tool's exact purpose unmistakable.

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

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

It provides explicit when-to-use guidance with 'ALWAYS trigger on' plus examples, and an explicit exclusion ('Skip task-specific requests'). However, it does not name alternative tools to use in the exclusion case, only says to skip, so the agent must infer the alternative.

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

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

With no annotations provided, the description carries the full burden. It extensively discloses side effects: queues proposals, writes a durable summary, backs up the original, clears the inbox copy, and defers memory pinning until 'dim review'. This exceeds expectations and prevents surprise.

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, front-loaded with the main purpose, and every clause provides essential information. It is efficient and well-structured without redundancy.

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

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

Given no annotations and no output schema, the description covers all critical aspects: purpose, source, sequence, side effects, and post-conditions. It even references the external prompt for further guidance. Extremely complete for a 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 description coverage is 100%, so the baseline is 3. The description adds context about the origin of claims but does not meaningfully enhance the parameters beyond what the schema already explains ('exactly as shown by knowledge_pending', '0–12 durable, scoped, falsifiable claims').

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 the action ('Submit'), the object ('FALSIFIABLE claims'), and the source ('pending knowledge doc'), distinguishing it from siblings like knowledge_pending and memory_write. It also specifies the outcome ('Queues them as proposals'), leaving no doubt about the tool's role.

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 conveys when to use ('from a pending knowledge doc') and references a workflow step ('see the knowledge_ingest prompt'), but does not explicitly list alternative tools or when not to use this tool. The 'only after dim review' note implies a follow-up process, adding useful 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 are provided, so the description carries the full burden. It clearly states this tool only lists documents and that processing is done separately via knowledge_ingest, which discloses the non-mutating nature. However, it doesn't elaborate on return format or pagination, but for a simple list operation 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 exactly two sentences: the first states what the tool does, the second provides usage context. No wasted words, information is front-loaded, and every phrase contributes 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?

Considering there are no parameters and no output schema, the description provides enough context for the agent to understand the tool's role and how to integrate it with knowledge_ingest. It could mention the nature of the returned list (e.g., titles, IDs), but given the simplicity, this gap is minor.

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

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

There are zero parameters and schema coverage is 100%, so the description need not add parameter details. The baseline for 0 params is 4, and the description appropriately focuses on purpose rather than parameters.

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

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

The description begins with a specific verb ('List') and a clear resource ('documents waiting in the knowledge inbox'). It also states the ultimate purpose ('to be summarized into pinned-on-approve memory proposals'), which distinguishes it from sibling tools like knowledge_ingest_submit or proposals_pending.

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

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

Explicit usage guidance is provided: 'Use with the knowledge_ingest prompt to process them in-session.' This tells the agent when and how to use this tool in combination with another, making the workflow clear without needing to infer.

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

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

No annotations are provided, so the description carries the full burden. It clearly establishes this is a pre-edit check and states what it returns (a decision and matching memories), implying a read-only, non-destructive operation. It doesn't explicitly state side-effect-free, but 'check' and 'return a decision' strongly imply no mutation. Slightly better if it stated 'does not modify anything'.

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 purpose-built sentences: the first states what the tool does and what it returns (decision types), the second states the exact call condition. Front-loaded with 'Pre-edit safety check'. 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?

4 params fully covered in the schema registered at 100% coverage)Skip. The description adds the decision semantics (proceed/ask_first/stop) and the before-editing usage contextcars. A safety-check tool with no output schema benefits from the explicit return value list, which it provides. Slightly light on what 'matching' means (keyword/path matching), but the schema's param descriptions handle that.

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?

Every parameter (diff, task, paths, agent_id) is described in the schema with 100% coverage, so the baseline is 3. The description reinforces purpose (diff vs task/paths matching) but doesn't add semantics beyond the schema. Acceptable but not additive.

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

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

The description names the exact verb ('check'), resource ('FAILED_APPROACH, GUARDRAIL, INVARIANT, or CONVENTION memories'), and the decision output (proceed, ask_first, stop). It also distinguishes the matching scope (diff or task/paths), so an agent knows exactly what this tool does and what it returns.

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 tells the agent WHEN to call: 'BEFORE editing code' and 'when the task touches an area with known historical failures or explicit rules.' It also explains the diff-or-description fallback semantics. This is prescriptive and the tool names its output decision clearly.

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 burden of disclosure. It explains that the tool is grounded in verified memory and not another model's opinion, and implies it reports guardrail violations and contradictions. However, it does not explicitly state the return format, whether the tool is read-only, or any side effects. This is a gap, but the description does provide some 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 three concise sentences, front-loaded with the main purpose. Every sentence adds value: the first states what it does, the second gives the critical timing, and the third reinforces the priority. No fluff or repetition.

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

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

Given the tool's simplicity (2 params, no output schema), the description provides strong contextual guidance about when to call it and its grounding. It implies results will identify violations and contradictions, but it does not explicitly describe the return value or format. A richer description of the output would make it complete, but the current level is adequate.

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 fully documents both parameters. The description adds little beyond the schema for parameters; it echoes the summary purpose ('what you just did or plan to do') but does not provide new parameter-level insight. 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 function: 'Review what you just did (or plan to do) against the project's VERIFIED memory and guardrails.' It uses a specific verb ('Review') and resource ('VERIFIED memory and guardrails'), and differentiates itself from sibling tools by calling itself a 'second critic' grounded in 'real, falsifiable beliefs rather than another model's opinion'.

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

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

The description gives explicit guidance on when to use the tool: 'Call BEFORE committing or proposing memories.' It also instructs to 'Resolve guardrail violations and contradictions first,' which clarifies the intended sequence. This distinguishes it from alternatives like memory_write or memory_propose.

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

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

No annotations are provided, so the description carries the full burden for side-effect transparency. The verb 'get' implies read-only behavior, but the description does not explicitly state that it performs no modifications, nor does it mention any auth/rate/side-effect details. It adds useful context about the content (conventions, gotchas) but falls short of explicitly disclosing non-mutation behavior.

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

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

The description is a single, front-loaded sentence that immediately states the core purpose and adds a clarifying list of content types (conventions, gotchas, invariants). There is no redundant wording or filler; every word serves to explain the tool's function.

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

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

For a simple read-oriented tool with full schema coverage for both parameters and no output schema concerns (it's a get), the description is sufficiently complete. It covers the what, when, and what kind of results (memories relevant to files). It does not mention pagination behavior, but that is not critical given the limit parameter and the absence of an output schema requiring explanation.

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

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

Schema description coverage is 100%, with both parameters (paths and limit) fully described in the schema, including details like 'Repo-relative file paths you are about to read or edit' and the limit range/default. The tool description does not add additional meaning beyond what the schema already provides, so the baseline score of 3 is maintained.

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 'Get all memories relevant to specific files' with a specific verb (get), a specific resource (memories for files), and a defined context (before editing). It distinguishes from sibling tools like memory_search (general search) and memory_write (writing) by explicitly tying to file paths and pre-edit usage.

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

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

The description provides a clear 'when to use' by saying 'before editing them,' which is a practical trigger. It does not explicitly state when not to use it or mention alternative tools, but the contextual purpose is strong enough for an agent to decide. Slight deduction for lacking explicit exclusions.

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

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

With no annotations provided, the description carries the whole disclosure burden. It does disclose the key output (a clear STOP/PROCEED decision) and the evaluation basis (NEVER guardrails, FAILED_APPROACH). It remains silent on whether the call is read-only, whether violations mutate state, or any side effects, though the tool reads as a non-destructive check.

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 compact, front-loaded sentences. The opening states the purpose, the next sentences cover input, evaluation criteria, return value, and usage timing. Every sentence earns its place with zero filler.

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

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

For a check tool with 3 parameters, no output schema, and no annotations, the definition is nearly complete: it explains purpose, inputs, the returned decision, and when to call. The only residual gap is that NEVER/FAILED_APPROACH semantics are not defined, though these are likely domain concepts shared with the sibling suite.

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 both required parameters (file_path, code) plus agent_id are fully documented in the schema. The description echoes those inputs ('Given a file path and the code you're about to write') without adding syntax or format details, which matches the baseline 3 for high schema coverage.

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

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

Opens with the specific verb+resource ('Pre-edit guardrail check') and elaborates what it checks (NEVER guardrails, FAILED_APPROACH warnings) and what it returns (STOP/PROCEED decision). The check is clearly a pre-write validation, distinct in intent from sibling tools like memory_write or memory_check_change, so an agent can tell them apart.

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?

'Call this before writing to files in protected areas' provides an explicit when-to-use condition. It does not, however, name alternatives or state when not to use it — e.g., that this is only needed for guarded paths and not for ordinary edits — so it stops short of a full 5.

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

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

With no annotations, the description carries the burden. It discloses that the memory is proposed for review rather than directly written, and that it's for uncertain knowledge. However, it doesn't detail side effects (e.g., whether it persists immediately, returns a proposal ID, or blocks). This is a gap but the core behavior is clear.

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 zero fluff. Purpose is front-loaded, usage guidance follows, and the tool is distinguished from memory_write efficiently. 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?

For a 10-parameter tool with full schema descriptions, the description provides sufficient usage context and differentiates from siblings. It doesn't cover return values, but no output schema exists and the core action (proposing to review queue) is clear. Complete enough for an agent to decide when to call.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific details; the schema already documents each parameter, including conditional ones like 'applies_when' and 'guardrail_level'. The description does not need to repeat this.

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

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

The description clearly states the action ('Propose a memory for the human review queue') and explicitly contrasts it with memory_write for inferred/uncertain knowledge. This distinguishes it from sibling tools without requiring schema inspection.

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

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

It gives explicit guidance: 'Use at SESSION END for learnings that should persist but warrant review' and 'Prefer this over memory_write for inferred/uncertain knowledge.' This provides both when-to-use and when-not-to-use conditions, routing the agent to the correct tool.

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

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

With no annotations, the description carries the full burden. It discloses a key behavioral consequence: 'Refuted memories are kept as negative knowledge,' indicating a non-destructive action and a persistent outcome. It also mentions the optional superseding connection. It stops short of describing return values or permissions, but the most important behavior is 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?

Three short sentences, with the main verb+resource in the first sentence. Each sentence provides distinct value: the action, the optional parameter, and the behavioral consequence. No redundancy or filler, making it highly 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?

For a tool with only two parameters and no output schema, the description supplies all essential context: what it does, when to use it, the optional input, and the outcome (negative knowledge). It's self-contained and leaves no critical gaps for an agent to invoke it 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 schema already describes both parameters with 100% coverage. The description adds context by explaining that the 'superseded_by' parameter is optional and its purpose ('Optionally provide the id of a new memory that supersedes it'), which reinforces the schema. It doesn't introduce new parameter details beyond that, matching the baseline for well-covered schemas.

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

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

The description opens with a specific verb+resource: 'Mark a memory as REFUTED' and clarifies the action's trigger. It distinguishes this tool from siblings like memory_verify or memory_write by focusing on the unique refutation action, so there's no ambiguity about its purpose.

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 you discover it no longer holds.' It also indicates the optional behavior of providing a superseding memory, which guides usage in that scenario. However, it doesn't name alternative tools or explicitly state when NOT to use it, so it's clear but not exhaustive.

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

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

With no annotations, the description carries the burden of behavioral disclosure. 'Search' implies a read-only operation and the 'use before exploring' hint is useful, but the description does not disclose details like whether results are limited to verified memories by default, how status filters interact, or what the return shape is.

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-load the action and purpose, then add a clear usage directive. Every word earns its place; no filler or redundant restating of the tool name.

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

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

For a simple query tool with 100% schema coverage and no output schema, the description captures the essential purpose and usage context. It lacks a note about the result format or default verification scope, but is otherwise sufficient for an agent to decide when to call it.

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

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

Input schema coverage is 100%, so the schema fully documents all parameters. The description adds context by listing some memory kinds, but this mostly duplicates the enum values already present in the schema, so no significant new parameter meaning is added.

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 ('Search') and a clear resource ('the repo's verified memory'), and enumerates the memory kinds it can retrieve. This distinguishes it from sibling tools like memory_write, memory_verify, and memory_get_for_files.

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 timing guidance: 'Use BEFORE exploring the codebase — past sessions may already know the answer.' It does not mention when not to use it or explicitly name alternative tools, but the context 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?

With no annotations, the description carries the full burden. It conveys that the operation is read-only ('Get a summary') and specifies the type of output ('counts by verification status and kind'). However, it does not clarify potential meanings of 'verification status' or 'kind,' nor does it disclose any limitations or side effects. Since this is a zero-parameter read tool, the minimal disclosure is acceptable but not particularly rich.

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, well-structured sentence that front-loads the action ('Get a summary') and efficiently conveys the result type. There is zero waste, and every word contributes meaning.

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 parameters and no output schema, the description provides sufficient context about what it returns ('counts by verification status and kind'). It could be slightly more explicit about the exact response format, but given the tool's simplicity, the description is nearly 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 tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameters, and the schema coverage is trivially 100%. No additional parameter semantics are required.

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

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

The description uses a specific verb ('Get a summary') and identifies the resource ('the repo's memory store') and scope ('counts by verification status and kind'). This clearly distinguishes it from sibling tools like memory_search or memory_get_for_files, which focus on retrieving individual memories rather than aggregate summaries.

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 the tool is for obtaining an overview of the memory store's contents, but it does not explicitly mention when to use this over alternatives, nor does it state any exclusions. It provides clear context but lacks explicit comparison to sibling tools.

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

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

With no annotations provided, the description must carry the full transparency burden. It discloses that the tool runs cheap evidence checks and updates memory statuses, indicating a mutating action, but does not specify what statuses change, whether changes are reversible, or any permission requirements. The context about 'cheap' checks is useful but side effects remain under-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 two well-structured sentences: the first states the action with specific evidence check names, and the second gives usage guidance. It is front-loaded, concise, and contains 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?

The tool has only two optional parameters and no output schema, so the description covers the essential aspects: purpose, usage context, and check types. It lacks details about return values and deeper side effects, but given the tool's moderate complexity, the description is fairly complete.

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

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

The input schema provides complete descriptions for both parameters (ids and deep), with 100% coverage. The description adds minimal contextual value beyond the schema, mentioning verification by id but not adding detail about deep or other semantics. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: re-run cheap evidence checks (STATIC_CHECK, COMMIT_REF) and update memory statuses. It names specific check types and the affected resource, distinguishing it from siblings like memory_search or memory_write by focusing on verification and status updates.

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 specifies when to use the tool: before relying on VERIFIED memories if the repo may have changed, or to verify specific memories by id. It provides clear usage context, though it doesn't mention when not to use it or alternative 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 carries full responsibility for disclosing behavioral traits. It adds value by emphasizing falsifiability and the guardrail_level requirement, but it does not describe side effects (e.g., whether it overwrites existing memories, validates evidence, or returns a confirmation). It is a mutation tool, and such omissions are notable.

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

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

The description is three sentences with no wasted words. It front-loads the primary purpose, then provides the most critical usage constraint (falsifiability), then the conditional guardrail instruction. Every sentence contributes to correct usage.

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

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

Given the tool has 7 parameters (2 required) and no output schema, the description is reasonably complete for authoring a memory. However, it does not mention what the tool returns or any effects on existing memories (e.g., conflict resolution, deduplication, idempotency). For a write operation, some expectation-setting on return or failure modes would improve completeness.

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

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

Schema description coverage is 100%, so on its own the schema documents all parameters. The description repeats the falsifiability requirement from the claim schema and the guardrail_level requirement from its schema, adding little new meaning beyond a stylistic emphasis on evidence. It does not explain parameter relationships or edge cases 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?

The description clearly states the action ('Persist a new memory') and the resource ('about this codebase'). It goes beyond a tautology by specifying the required format for the claim (falsifiable) and guidance on evidence. It does not explicitly contrast with siblings like memory_propose or memory_search, but the purpose is distinct enough for an agent to recognize it as the write operation.

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

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

The description provides clear context on when to use the tool ('Persist a new memory') and offers specific conditional guidance for GUARDRAIL kind. It does not mention when not to use the tool or name alternative tools, but the 'when' is unambiguous. The advice to attach evidence whenever possible gives usage direction.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'Listing' implies a non-mutating operation, which is clear. However, it doesn't clarify details like order of results, whether it includes historical proposals, or behavior when no proposals exist. It's adequate but lacks depth.

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

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

A single, clear sentence in an active voice. It contains no fluff and immediately conveys the action and the target resource. Perfectly 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?

Given a simple tool with only one optional parameter, the description is sufficient for basic usage. It doesn't mention any default order or if there's a way to filter by status beyond 'pending,' but that's minor for a listing tool. It's complete for its simplicity.

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

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

Schema coverage is 100% with the only parameter 'limit' well-documented (range, default). The description doesn't need to add much. The parameter's meaning is immediately clear from the schema, so the description adds little extra beyond the schema.

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

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

The description clearly states the tool lists memory proposals pending human review, using the specific verb 'list' and resource 'memory proposals'. It could better distinguish from 'knowledge_pending' but the scope ('awaiting human review') adds useful context that differentiates it from 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 implies a read-only listing action suitable for review workflows. It doesn't explicitly state when to use this over alternatives like search or knowledge_pending, but the term 'awaiting human review' indirectly signals its purpose. No explicit exclusions to siblings are provided.

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 must disclose behavioral traits. It does not mention that clearing is irreversible, whether any confirmation is required, or what happens to the data. As a destructive operation, this lack of safety information is a significant 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 short sentences: the first states the action, the second gives the usage context. No filler words, clearly front-loaded, and 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 tool is simple with one optional parameter and no output schema, so the description is mostly adequate. However, for a destructive clear operation, it should disclose irreversibility or side effects; without this, the description leaves a gap in the agent's ability to anticipate consequences.

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

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

The schema already fully describes the session_id parameter ('Only clear this session key; omit to clear all'). The description adds no new meaning beyond restating this, so it provides no additional value over 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 explicitly states the action ('Clear scratchpad working notes') and scope ('one session key, or everything'), using a specific verb and resource that clearly distinguishes it from sibling tools like scratchpad_read and scratchpad_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?

It provides clear context ('Use when a task completes and its intermediate state is no longer needed') that tells when to invoke the tool. However, it does not explicitly name alternative tools or state when not to use it, though the context strongly implies a cleanup role.

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 adds useful behavioral context: notes are from the current session, returned newest first, and expired/old notes are automatically purged ('Expired notes are automatically cleaned up'). This goes beyond the schema, though it doesn't mention read-only safety explicitly (but that's implied by 'read').

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 purpose, every clause adds value: what it does, ordering, when to use, and note retention behavior. 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 read operation with only two optional parameters, this is nearly complete. It covers purpose, usage timing, and the auto-purge behavior. Lacks explicit return type description, but without an output schema and given the simplicity, it's adequate. Could benefit from noting it returns only unexpired notes (implied by purge).

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 with descriptions including defaults. The description adds no additional parameter context beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool reads short-term working notes from the current session's scratchpad, with a distinctive 'newest first' ordering. It uses a specific verb+resource construction and is distinguishable from sibling tools like scratchpad_write and scratchpad_clear.

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

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

Explicitly states when to use it ('when resuming a task to recover in-flight state'), providing clear context. It doesn't explicitly say when NOT to use it (e.g., vs memory tools), but the 'short-term' qualifier implies a distinction from long-term memory.

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. It discloses key behavioral traits: 'Auto-expires (default 24h)' and 'is never synced', plus the non-durable nature. It does not specify whether writing replaces or appends existing notes for the same session_id, which is a minor gap, but overall it covers critical transient behavior.

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, followed by key caveats and alternatives. No wasted words; 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?

For a 3-parameter write tool with no output schema and no annotations, the description covers purpose, usage guidance, lifetime, sync behavior, durability distinction, and session scope. It is sufficiently complete for an agent to decide when and how to use the 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?

The schema covers 100% of the parameters with descriptions, so the baseline is 3. The description redundantly mentions 'default 24h' which is already in the schema, and it does not add significant meaning beyond what the schema provides for 'content', 'ttl_hours', or 'session_id'.

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 the specific verb 'jot' with a clear resource and scope: 'SHORT-TERM working note for the current session' with examples of content. It explicitly distinguishes from durable memory by naming 'memory_write/memory_propose', which differentiates from sibling 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 provides explicit when-to-use context: for intermediate findings, plans, hypotheses, task state in the current session. It gives a clear exclusion: 'NOT durable memory — use memory_write/memory_propose for knowledge that should persist across sessions', naming 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?

No annotations are present, so the description must carry the burden of behavioral disclosure. It implies a read-only fetch and explains auto-detection from the branch, but it does not explicitly state that it is side-effect-free or describe behavior when no ticket is found.

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

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

Two concise sentences: the first states the primary function, the second provides usage timing and rationale. No redundant words 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?

For a simple tool with one optional parameter and no output schema, the description covers what is fetched, the param behavior, and when to use it. It does not describe the return format, but the listed fields partly compensate.

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

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

The schema description fully covers the id parameter, including the omission auto-detection behavior. The description repeats this but adds no new information, so baseline 3 is appropriate given 100% schema coverage.

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

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

The description opens with a concrete verb 'Fetch' and a specific resource ('the ticket behind the current work') plus the fields returned (title, description, type, status). This clearly distinguishes it from sibling memory/scratchpad 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 gives explicit usage context ('Use at session end') and explains the value ('the ticket carries the WHY that commits lack'), which is clear guidance. It does not mention when not to use it or alternatives, but no direct alternatives exist among siblings.

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