kit-memory-demo

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

Annotations provide only title, so description must carry behavioral weight. It implies a read-only list operation but does not explicitly confirm no side effects or state what 'Lady Whiskerdown' means. Adequate for a simple tool but lacks explicit safety guarantees.

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

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

Single sentence of 9 words with zero fluff. Every word is necessary for the core function.

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

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

Despite no output schema, the description fails to hint at response format or what a 'knowledge area' constitutes. A simple tool still needs to inform the agent about what to expect in return.

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

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

No parameters exist; baseline score is 4 as per rubric. Description adds context about 'knowledge areas' and 'Lady Whiskerdown' which marginally enhances understanding beyond the empty schema.

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

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

Description uses specific verb 'List' and resource 'knowledge areas', clearly distinguishing from sibling tools which are action verbs like capture, commit, focus.

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

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

No guidance on when to use this tool versus alternatives; no mention of prerequisites or context where this listing is appropriate.

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

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

Annotations only provide a title, so the description carries the full burden for behavioral disclosure. It states that the tool extracts memories and saves drafts, indicating a write operation. However, it does not explain whether drafts are persistent, how to review them, or any side effects (e.g., does it consume the transcript?). The description is adequate but not rich in 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?

Two sentences, zero wasted words. The first sentence states the core purpose, the second provides usage guidance. Information is front-loaded and every sentence earns its place. Ideal structure for an agent to quickly parse.

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 6 parameters (1 required) and no output schema. The description covers purpose and usage but omits crucial details: What does the tool return? Are drafts accessible immediately? Are there any error conditions or prerequisites? The agent is left guessing about the outcome and next steps. Given the absence of an output schema, the description should compensate with at least a hint of the return value or side effects.

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 does not add parameter-specific information beyond what the schema provides. The schema descriptions are already clear and complete (e.g., 'transcript' format, 'source' default, 'max_drafts' cap). The description adds no extra value for parameters, maintaining 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 uses a specific verb-resource combination: 'Extract candidate memories from a session transcript and save them as drafts.' This clearly distinguishes 'capture' from sibling tools like 'remember' (direct storage), 'note' (manual note-taking), and 'recall' (retrieval). The purpose is unambiguous and unique.

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 the tool: 'Use near the end of a meaningful session when the transcript contains decisions, gotchas, or reusable context.' This provides clear situational guidance. It does not explicitly mention when not to use it or name alternatives, but the positive conditions are sufficient for an agent to decide contextually.

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?

Beyond the bare title annotation, the description discloses the key behavioral trait: the memory is 'durable' and 'searchable later,' which tells the agent this is a persistent write. It does not enumerate every side effect, but the schema's detailed parameter descriptions cover mechanics like deduplication and category registration, so the tool-level behavior is adequately 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?

Two short sentences, with the core action front-loaded and the usage constraint following immediately. Every phrase earns its place; there is no filler, redundancy, or unnecessary preamble.

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 gives an agent enough tool-level context to know this is the durable-memory write operation, and the schema's rich parameter descriptions handle the details of category, tier, scope, surface, and dedup. It does not explicitly guide the agent away from sibling tools like 'remember' or state what the function returns, which are the only notable 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?

With 100% schema description coverage, the schema already documents all 14 parameters, including category slugs, tier semantics, and surface defaults. The description adds only high-level content guidance ('stable decisions, facts, gotchas, patterns') rather than parameter-level detail, so the value added is minimal and 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 opens with a specific action ('Add a durable memory') and a clear target resource (the 'knowledge corpus'), and qualifies the intended content ('stable decisions, facts, gotchas, or patterns'). However, it never names any sibling tool or explains how this differs from the similarly named 'remember' or 'note', so the differentiation is left implicit.

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 line 'Use only for stable decisions, facts, gotchas, or patterns that should be searchable later' provides an explicit inclusion criterion, telling the agent when to invoke the tool. It does not explicitly say when to use an alternative (e.g., a transient note) or name any of the sibling tools, so the guidance is strong but incomplete.

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

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

Annotations are minimal (only title provided), so the description carries the full burden. It discloses persistence behavior (holds until change or TTL) and override rules, which is helpful. However, it does not mention side effects (e.g., immediate vs. lazy writes), error cases, or authentication needs. The schema covers clearing behavior (empty string clears to General), but the description does not reinforce that. For a mutation tool, more transparency about impacts would raise the score.

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 with no dead weight. The first sentence front-loads the purpose and inputs. The second sentence delivers critical behavioral context (persistence, TTL, override). Every part earns its place, and the structure is scan-friendly for an AI agent.

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 covers necessary context: what the tool does, its scope (writes focus), persistence rules, and interaction with other tools. It does not describe the return value (likely empty or success indication) or error scenarios, but for a simple setter with two optional string parameters, the provided information is largely sufficient. The absence of output documentation is a minor gap, leaving the agent to infer success/failure from implicit convention.

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 minimal value beyond the schema; it merely paraphrases 'knowledge area' and 'project' without providing format examples, constraints, or context about valid slugs. It does not enhance the agent's understanding of how to construct parameter values beyond what the schema already offers.

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 tool sets the operator's write focus by specifying knowledge area and optionally project. It clearly distinguishes from siblings like 'capture', 'commit', or 'note' by being the dedicated focus-setter. It also notes it is called by the wake card's chips, providing context without ambiguity.

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 that the focus holds until changed or idle past TTL, and that explicit area/project arguments on commit/note/handoff take precedence. This gives clear context on when the effect persists and how it interacts with other tools. However, it lacks explicit negative guidance (e.g., when not to use) or direct comparison to sibling alternatives despite having a unique 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?

Annotations provide no behavioral hints (no readOnlyHint, destructiveHint, etc.), so the description must carry the full burden. The description only states that the tool writes a handoff, but does not disclose whether this is a persistent action, requires authentication, or has any side effects. The agent is left guessing about the tool's impact on state.

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

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

The description is a single sentence that efficiently conveys purpose and usage conditions. There is no wasted text; every clause adds value. It is appropriately front-loaded with the core action ('Write a concise handoff') followed by the when-to-use list.

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 (6 parameters, no output schema, minimal annotations), the description adequately explains when to use but does not describe what happens after writing (e.g., persistence, visibility, return value). The schema covers parameter details, but the agent lacks context on the tool's lifecycle and post-invocation behavior.

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 does not add any parameter-specific meaning beyond what the schema already provides (e.g., the schema already explains 'title' with an example, 'content' with structure). The description's value is in usage context, not parameter elaboration.

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: 'Write a concise handoff for the next agent/surface'. It lists specific triggering scenarios (session end, topic change, etc.), making the verb and resource distinct. Among sibling tools like 'note' or 'commit', this purpose is unique and unambiguous.

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 when-to-use conditions: 'at session end, topic change, substantial completed work, or a long-session restart point'. It does not directly contrast with alternatives, but the listed scenarios are specific enough to guide appropriate use. A score of 5 would require mentioning when not to use or naming a specific 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 only a title in annotations, the description carries the behavioral burden, and it delivers useful context: the tool writes a live shared checkpoint visible to other surfaces. It also constrains the handoff kind to specific situations, which clarifies behavior beyond the enum. It does not discuss persistence details, retention, or auth, but for a simple note-writing tool the disclosed behaviors suffice.

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

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

Two sentences, no filler, and front-loaded with the core action. The first sentence establishes what the tool does, and the second adds precise usage constraints. Every clause earns its place.

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

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

The description covers the tool's core behavior, when to use it, and the critical handoff constraint. With 9 parameters and no output schema, the description could go further on what happens after a note is written, but the input schema documents the parameters well and the operational context is clear enough 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?

Schema description coverage is 100%, so the baseline is met by the schema itself. The description adds value by giving semantic guidance for the kind parameter, notably restricting handoff usage to specific scenarios. It also ties checkpoint kinds to operational lifecycle moments, which helps the agent choose appropriate values.

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: 'Write a live operational checkpoint' that other surfaces can pick up. It clearly indicates the tool's purpose and scope, and the list of lifecycle moments (start, diagnosis, pivot, blocker, etc.) adds specificity. It does not explicitly distinguish itself from sibling tools like capture, remember, or commit, but the 'operational checkpoint' framing is distinctive enough.

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 concrete when-to-use direction: 'Use at start, diagnosis, pivot, blocker, commit, verification, and resume.' It also gives an explicit exclusion for kind=handoff, limiting it to session end, topic change, substantial completed work, or long-session restart points. It does not explicitly name alternatives among sibling tools, but the situational guidance is strong.

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

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

Annotations only provide a title; description adds 'live' and 'within the requested window' context. It does not disclose effects (none expected for a read), data freshness guarantees, or any rate limits, but this is acceptable for a simple read tool.

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

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

Single sentence, front-loaded with verb 'Read' and object. No wasted words. Could be slightly more specific about the meaning of 'facet presence' but still 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?

Given 2 optional params, 100% schema coverage, and no output schema, the description is adequate for a simple read tool. However, the lack of sibling differentiation and the cryptic 'Lady Whiskerdown' phrase create minor 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 does not add extra meaning beyond the schema for 'scope' and 'window_minutes', but that is compensated by the schema's own descriptions.

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

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

The description clearly states it reads 'live Lady Whiskerdown facet presence' within a window, distinguishing it as a read tool. However, the term 'Lady Whiskerdown' is cryptic and may confuse the agent.

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 the tool is for reading presence data within a time window but does not explain when to use this over siblings like 'areas' or 'wake'. No exclusions or alternatives 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?

Annotations only provide a title, so the description carries the full burden of behavioral disclosure. The description notes that the tool performs a semantic search and returns memories scoped to the agent's knowledge area, implying a read-only operation. However, it does not explicitly state that it is non-destructive, does not describe any side effects, rate limits, or authorization requirements. The behavior is adequately described for a simple search, but lacks explicit transparency about safety and constraints.

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 consists of three sentences: the first states the core action, the second provides usage guidance, and the third describes the return. It is front-loaded and efficient, with no extraneous information. It could be slightly more compact (e.g., merging the first two sentences), but overall it is well-structured and concise for a tool of this complexity.

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 two parameters, no output schema, and no nested objects. The description covers the purpose, usage context, and return type (memories). However, it does not describe the output format or structure, nor does it mention error handling, pagination, or the exact scope of 'knowledge area'. Given the absence of an output schema, the description should provide more detail about what the agent can expect to receive. The description is adequate but incomplete for a standalone specification.

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

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

The input schema already has 100% description coverage: 'query' is described as 'What to search for, in natural language' and 'limit' as 'Max results (default 10)'. The description adds 'semantic search' and 'scoped to your knowledge area', which are general context, but does not provide additional meaning or constraints for the parameters beyond what the schema already states. Per the rubric, with high schema coverage, the baseline is 3, and the description does not significantly enhance parameter semantics.

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: 'Recall this Lady Whiskerdown's knowledge by semantic search.' It specifies both the action (recall) and the resource (Lady Whiskerdown's knowledge). The mention of returning 'the most relevant memories you have access to, scoped to your knowledge area' further clarifies the output. The usage context ('Use before answering any user question about this Lady Whiskerdown...') and the sibling tools (e.g., 'remember' for storing, 'areas' for listing) distinguish this tool as a retrieval mechanism.

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

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

The description explicitly states when to use the tool: 'Use before answering any user question about this Lady Whiskerdown, the customer/product, project facts, onboarding, architecture, policies, product decisions, or imported documents.' This provides a clear set of scenarios. However, it does not mention when NOT to use it or suggest alternative tools (e.g., 'remember' for storing, 'focus' for setting context). The instructions are straightforward but lack exclusions, so a score of 4 is appropriate.

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

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

Annotations provide no readOnlyHint or destructiveHint, so the description carries the full burden. It clarifies the read nature and scoping, but lacks details on authentication, error behavior, or idempotency.

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

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

A single, front-loaded sentence with no fluff. Every part serves a purpose: verb, resource, scope, and key differentiation.

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 tool with one parameter and no output schema, the description covers purpose, ID format, and what the tool does not do (enrichment). It is missing error handling or output format details but is largely complete.

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

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

Schema coverage is 100%, and the schema already describes the 'id' parameter as 'Memory id (number or m#N as shown by recall)'. The description adds only a reference to recall, not new 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 clearly states it reads a single memory by ID, specifying it returns the memory itself without graph/enrichment. It explicitly distinguishes from sibling 'recall' by noting IDs come from recall.

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

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

The description tells when to use (to retrieve a specific memory by ID from recall) and what not to expect (no graph/enrichment). It does not explicitly name alternatives beyond recall, nor state when not to use.

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

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

The description discloses that the returned identity is 'offered, not imposed' and explains how the agent should handle it. With only a title annotation (no destructive or read-only hints), the description takes on responsibility for behavioral info. It could mention side effects (none expected) or state that this is a read operation, but the behavioral context is still strong enough to score 4.

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 key call to action and purpose, but it is somewhat long (five sentences) and includes narrative details ('Lady Whiskerdown', 'key') that could be compressed. Every sentence adds value, but the style is more verbose than necessary for an AI agent.

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 (1 optional enum parameter, no output schema, no nested objects), the description is complete. It explains what the tool returns, when to call it, how to use the returned data, and how it relates to sibling tools. No gaps remain for the agent to misunderstand.

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 0%, so the description must compensate for the 'scope' parameter. While it doesn't explicitly describe 'scope', the context of 'work', 'personal', 'all' is intuitive given the tool's purpose of initializing a session. The enum values are self-explanatory and the description's overall clarity reduces ambiguity. A 4 is appropriate as the description provides enough context to infer parameter usage.

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: it initializes a new chat session by returning identity, knowledge scope, tools, and working contract. It specifies when to call it ('FIRST in every new chat') and distinguishes it from siblings like 'recall'.

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

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

Explicitly says 'Call this FIRST in every new chat (VS Code/Copilot, Cursor, Claude Code, Codex), before the first substantive answer.' It also provides a clear when-not-to-use: 'For anything this Lady Whiskerdown should know, call recall first instead of using general model knowledge.' This differentiates it from the sibling tool 'recall'.

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