kit-memory-demo

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 only says 'List...' without disclosing side effects, authorization needs, return format, or limitations. This provides minimal insight beyond the action itself.

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, clear sentence that conveys the essential purpose without any unnecessary words. It is optimally concise and front-loaded.

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

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

For a zero-parameter operation, the description clearly states the action and object. While it does not describe return values or caveats, the tool's simplicity makes the description reasonably complete.

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

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

The tool has zero parameters and the schema description coverage is 100% (no properties). Per the rubric, a baseline of 4 is appropriate since there is no parameter semantics to clarify.

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 ('List') and clearly identifies the resource ('knowledge areas') with a scope ('in this Kit'). This distinguishes it from sibling tools like capture, commit, handoff, 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?

The description does not mention when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites. It simply states what the tool does without guiding the agent on selection.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clarifies the tool saves drafts rather than final memories, which is useful. However, it does not describe side effects, storage implications, or what happens to the drafts after review, leaving some behavioral ambiguity.

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 with no redundant wording. The first sentence states the core function, and the second provides usage guidance. Both earn their place and the structure is front-loaded with the verb.

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 six parameters, no output schema, and no annotations. The description explains what and when, and the schema covers some parameters, but it omits expected return values or what the agent should do after invocation. This is acceptable for a basic capture tool but leaves some gaps for full autonomous use.

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

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

Schema description coverage is 50%, covering source, max_drafts, and transcript. The description adds meaningful semantic context for the transcript parameter (candidate memories, decisions, gotchas) but does not help clarify project, session_id, or contributor_model. It improves understanding but does not fully compensate for the missing parameter descriptions.

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

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

The description clearly states the specific action ('Extract candidate memories from a session transcript') and the resource ('save them as drafts for later review'). It distinguishes itself from siblings like remember and note by introducing the 'drafts for later review' concept, making its purpose unique and actionable.

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 the tool: 'near the end of a meaningful session when the transcript contains decisions, gotchas, or reusable context.' It does not mention exceptions or alternative tools, but the contextual guidance is clear and sufficient for most agents.

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 only reveals that the memory is durable and for stable content; it does not disclose deduplication behavior, whether existing memories are overwritten, required permissions, or return values. For a tool with 13 parameters, this is a significant transparency 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?

The description is two sentences, front-loaded with the action in the first sentence and usage guidance in the second. Every word earns its place.

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

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

Given the tool has 13 parameters, no annotations, and no output schema, the description is too sparse. It doesn't cover the memory lifecycle, deduplication, or the meaning of various parameters, leaving the agent underinformed.

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 covers only 15% of parameters with descriptions, and the description offers no parameter-level meaning. It does not explain how 'category', 'tier', 'scope', 'surface', or dedup settings work. The description's mention of 'durable memory' loosely maps to content/title but doesn't compensate for the low 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 clearly states the tool adds a durable memory to the Kit's knowledge corpus, using a specific verb and resource. It also distinguishes from sibling tools by specifying stable decisions, facts, gotchas, and patterns as appropriate content.

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 says 'Use only for stable decisions, facts, gotchas, or patterns,' giving clear when-to-use guidance. However, it does not explicitly name alternative tools for transient or other memory types, so it lacks 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action and timing but does not explain whether the handoff is stored, returned, overwrites existing data, or requires session context, leaving key behavioral aspects opaque.

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 one well-structured sentence that front-loads the core action and enumerates exact triggering scenarios. It contains no wasted words or redundancy.

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

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

For a simple write tool with a schema that documents most parameters, the description covers the purpose and timing but omits behavioral outcome (e.g., persistence/sharing) and alternatives. This is adequate for basic use but leaves important contextual questions unanswered.

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 descriptions cover 67% of parameters, including the important 'content' field that states what to include. The description adds the when-to-write context but does not explain the undecorated 'project' and 'session_id' parameters, so it only partially compensates for the schema gap.

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 specifies the verb 'Write' and the resource 'handoff' for the next agent/surface, with explicit trigger conditions (session end, topic change, substantial completed work, long-session restart). This distinct focus differentiates it from sibling tools like 'note' or 'capture', which are more general memory/record 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 triggers (session end, topic change, substantial completed work, long-session restart), giving clear contextual guidance. However, it does not mention when not to use it or name alternatives such as 'note' or 'remember', so exclusions are missing.

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 of behavioral disclosure. It does not mention side effects, persistence, visibility, permissions, or reversibility. The phrase 'live operational checkpoint' hints at sharing, but it does not explain what happens to prior notes, whether supersedes is used, or what the response looks like.

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 strong front-loading. The first sentence states the core purpose, and the second provides usage guidance. No wasted words, and the structure is easy to 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 description covers the core mechanism and usage timing, but for a tool with 9 parameters, no annotations, and no output schema, it lacks details about return values, side effects, and how parameters like supersedes or session_id affect behavior. It is adequate for basic invocation but leaves gaps for an agent needing to fully understand the tool's 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 coverage is 56%. The description adds meaning to the 'kind' parameter by mapping usage contexts (start, diagnosis, pivot, blocker, commit, verification) to enum values, but it does not clarify undocumented parameters like supersedes, session_id, collab, or project. It partially compensates for the coverage gap but does not fully explain all optional fields.

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: 'Write a live operational checkpoint so other Kit-connected surfaces can pick up the thread.' It uses a specific verb+resource construction (write/checkpoint) and distinguishes itself from the sibling 'handoff' tool by specifying when kind=handoff is appropriate.

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

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

The description provides explicit usage contexts: 'Use at start, diagnosis, pivot, blocker, commit, verification, and resume' and explicitly restricts kind=handoff usage to 'session end, topic change, substantial completed work, or long-session restart points.' This gives clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. The verb 'Read' implies a non-destructive operation, but the description does not elaborate on return format, error behavior, rate limits, or side effects. This is a minimal disclosure that fails to provide meaningful transparency for a tool with no annotation support.

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, concise sentence that front-loads the action ('Read') and resource ('live Kit facet presence'), with no wasted words. It is immediately understandable and structurally 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 one-parameter read tool, this description is minimally adequate. It defines the parameter's role via the phrase 'within the requested window,' but it leaves 'Kit facet presence' undefined and lacks any broader context about return values or operational expectations. The absence of an output schema and annotations makes this a modest but not severe gap.

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

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

The schema fully describes the single parameter 'window_minutes' with default and maximum values, giving 100% coverage. According to the baseline rule, a score of 3 is appropriate because the description itself adds no additional parameter meaning 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 begins with the verb 'Read' and clearly identifies the resource as 'live Kit facet presence' within a requested window, making the tool's function explicit. It does not explicitly differentiate from sibling tools, but the resource name is distinct enough that confusion is unlikely.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It only states the function without context regarding appropriate scenarios, leaving the agent to infer usage from the name and description alone.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is a non-destructive semantic search operation that 'returns the most relevant memories you have access to, scoped to your knowledge area.' This implies read-only behavior and access scoping, though it does not mention potential side effects, rate limits, or error cases. Still, the behavior is clear and not misleading.

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

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

Two sentences, no wasted words. The first sentence states the core purpose, the second covers usage timing and return behavior. Front-loaded and efficient.

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

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

For a simple 2-parameter search tool with no output schema, the description covers purpose, usage, and return type. It does not mention edge cases like empty results or pagination, but the schema documents 'limit', and the description's mention of 'most relevant memories' sets expectations. Sufficiently complete for this complexity.

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

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

Schema coverage is 100% with descriptions for both 'query' (natural language search) and 'limit' (max results, default 10). The tool description adds only marginal context by framing the query as a user question, but does not materially supplement the schema. Baseline 3 is appropriate.

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

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

The description is highly specific: 'Recall this Kit's knowledge by semantic search' names the action, target, and method. It further enumerates concrete use cases (customer/product facts, architecture, policies) and distinguishes itself from sibling tools like 'remember' or 'capture' by clearly indicating retrieval.

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

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

Provides clear when-to-use guidance: 'Use before answering any user question about this Kit, the customer/product, project facts, onboarding, architecture, policies, product decisions, or imported documents.' It does not explicitly state when not to use it or name alternatives, but the use case is well-defined enough to avoid confusion with siblings.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state the operation is a 'Read', indicating a non-mutating action, and notes the id source from recall. However, it lacks details on return format, error handling, or side effects, which limits transparency.

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

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

The description is a single, front-loaded sentence with no redundant information. It clearly states the action, resource, and parameter context without wasting words.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is largely sufficient. It explains what the tool does and where the id comes from. The return value is not explicitly described, but 'Read' implies returning the memory, so the 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?

The schema already describes the 'id' parameter as 'Memory id' with 100% coverage. The description adds the important semantic that the id must be one 'as returned by recall', which provides contextual meaning beyond the schema field description.

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

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

The description uses the specific verb 'Read' and identifies the resource as 'a single Kit memory', making the tool's function clear. It also distinguishes from sibling 'recall' by specifying that the id is obtained from recall, which clarifies its unique role in the workflow.

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 should be used after 'recall' to fetch a specific memory by id, but it does not explicitly state when to use it versus alternatives or provide exclusions. The usage context is implied rather than clearly stated.

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

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

With no annotations provided, the description fully carries the transparency burden. It discloses that the tool returns an identity (`you_are`), that this identity is 'offered, not imposed', and explains the conditional adoption rule. It also clarifies that the agent can answer as itself while reading the archive. This provides nuanced behavioral context beyond a simple 'wake up' verb.

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 multi-sentence but front-loaded with the critical 'Call this FIRST' instruction. Every sentence adds value: identity, output contents, identity adoption nuance, and a pointer to `recall`. It could be tightened slightly without loss, but it is not bloated.

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 purpose, timing, output summary, and identity handling. It lacks documentation of the `scope` parameter and does not provide a full return format, but given no output schema, the summary is sufficient for basic invocation. The existence of a working contract and knowledge-area enumeration gives enough context for an agent to proceed.

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

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

The description does not mention the `scope` parameter at all, and schema coverage is 0% (no description in the input schema). The parameter is enum-bound (work/personal/all) and optional, but its effect on the output is completely unexplained. Given low schema coverage, the description was required to compensate but failed, leaving a semantic gap.

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 ('meet', 'call') and resource ('Kit') and defines the primary purpose: initialize a new chat session with Kit's identity, accessible knowledge areas, tools, and working contract. It explicitly distinguishes itself from siblings by being the 'FIRST' call and by rerouting knowledge queries to 'recall', eliminating 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?

It gives explicit usage timing: 'Call this FIRST in every new chat... before the first substantive answer.' It also names an alternative ('call recall first') for knowledge-related queries, providing clear when-to-use vs when-not-to-use guidance without needing inference.

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