kit-memory-demo

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

Annotations contain only a title, so the description carries the full burden. "List" weakly implies a read, but there is no statement about read-only vs. mutating behavior, side effects, permissions, or whether kit_session_id is required in practice. For a tool with zero behavioral annotations this is a real 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?

A single short sentence, front-loaded with the verb, with no filler or hedging. The only cost is that the flavor phrase "this Lady Whiskerdown" consumes words without adding information.

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

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

For a listing tool with no output schema, the description should at least indicate what an "area" looks like in the response or how results should be used. Instead the agent learns only that a list exists, leaving the return shape and downstream usage unexplained.

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% and the single parameter kit_session_id is fully documented in the schema, including the subagent caveat. The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

"List the knowledge areas" gives a clear verb+resource, but the qualifier "in this Lady Whiskerdown" is an opaque in-joke that never defines what the resource actually is or where it lives. Nothing distinguishes it from siblings like systems, focus, or recall, which plausibly return related catalog-like data.

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 call this versus the other seven sibling tools, no prerequisite or ordering hint (e.g. call before recall/focus), and no exclusions. The agent must guess its place in the workflow.

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 beyond the title, the description carries the behavioral burden and discloses key stateful traits: the focus holds until changed or idle past the TTL, and explicit per-call arguments still win. It does not describe error behavior, permission requirements, or return values, but for a non-destructive focus-setting tool it provides meaningful operational 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 tight sentences with no wasted wording. It front-loads the core action and then adds persistence and override behavior in a logical order.

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 state-setting tool with full parameter schema coverage and no output schema, the description covers purpose, caller context, persistence, and precedence. It could additionally specify the TTL duration or failure behavior, but nothing critical for calling it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description adds useful meaning by explaining that area and project determine routing for new memories and that explicit arguments on commit/note/handoff take precedence, which is not expressed in the schema.

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

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

The description states a specific verb and resource: 'Set this operator's write focus: the knowledge area new memories are stored under, and optionally the project being worked on.' This clearly distinguishes the tool from storage/retrieval siblings like remember, recall, and areas by explaining that it configures routing for future writes rather than performing those writes.

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 clear usage context: wake card chips call it, and it is also directly callable. It also explains that the setting persists until changed or TTL expiry, and that explicit area/project arguments on commit/note/handoff override it. It lacks an explicit when-not-to-use statement, but the alternatives and precedence rules are clear.

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

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

Annotations supply only a title, so the description carries the full burden, and it under-delivers: it frames the tool purely as a read while the schema reveals a send mode with queueing semantics, 30-minute message expiry, refusal of quiet sessions, and no wake/spawn behavior. None of that side-effect profile appears in the description, so an agent reading only the prose would not anticipate the mutation path.

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?

One sentence is admirably short and front-loaded with the verb, so it passes the conciseness test. However, the economy comes at the cost of the tool's second mode and any usage context, so the brevity reads as under-specification rather than precision.

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 five-parameter tool with a dual read/send behavior, no output schema, and no meaningful annotations, a single read-only sentence is not enough. Key facts an agent needs before calling — the send mode, session requirements, delivery guarantees — exist only in the schema, leaving the description incomplete relative to the tool's complexity.

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

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

Schema coverage is 100% and the parameter descriptions are unusually thorough (address binding, scope defaults, 400-char limit, window default and max), so the schema does the heavy lifting. The description adds only the loose notion of a 'requested window', which maps to `window_minutes` but adds no format or constraint detail beyond the schema.

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

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

The description gives a verb+resource ('Read ... presence') within a time window, which is understandable in outline, but the phrasing 'Lady Whiskerdown facet presence' is domain jargon that doesn't tell an agent what data actually comes back, and it silently omits that the same call can send a message via the `to`/`message` parameters. It does not differentiate itself from siblings such as wake, recall, or 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?

There is no guidance on when to use this tool versus wake, recall, or focus, and no mention of prerequisites such as needing a session id from wake. The only positional hint is 'within the requested window', which is a scope statement, not 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?

Annotations carry only a title, so the description must carry the behavioral load. It does disclose the key filtering behavior ('returns every row whose rank or score changes') and the per-row payload (baseline rank, boosted rank, deltas, sample source, boost window, units), which is genuinely useful. It does not say whether the call is read-only, how expensive it is, or how it behaves when no boost has been learned.

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

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

Two sentences with zero filler; the comparison is front-loaded and the return shape follows immediately after. Nothing repeats the name or title.

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

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

With no output schema, the description correctly enumerates the returned row fields, and all parameters are covered by the schema. What is missing is the precondition and failure mode (no learned boost, empty sample), which matters for an agent deciding whether the call is meaningful.

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 all seven parameters are already documented in the schema, including the limit cap and the kit_session_id rules. The description adds no meaning beyond that and mentions only 'units', which is not a parameter. Baseline 3 applies.

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

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

States a specific verb and resource ('Compare search ranking for a query') plus the exact comparison basis (with vs. without the recently learned boost). No sibling in the list does ranking comparison, so no disambiguation is needed.

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?

Usage is only implied: an agent can infer this is a diagnostic for verifying boost effect, but the description never says when to reach for it versus recall, or what precondition (an existing learned boost / active session from wake) must hold.

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 carry only a title, so the description bears the full burden and does reasonably well: it discloses the access boundary ("entries this key can read"), the relevance-based result set, and a mandatory citation format agents must follow. It omits whether results are truncated or how ranking is computed, but the read-only nature is clear from "search".

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

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

Three sentences, front-loaded with purpose, then usage priority, then the required citation convention. No filler; every clause carries operative information for an 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?

With no output schema, the description usefully sketches the return shape by implying each entry has an identifier (`m#N`) and a title, and it explains the access scope. It leaves the entry payload structure and result truncation unstated, a minor gap for a simple three-parameter search tool.

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

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

Schema description coverage is 100%, and the parameters (`query`, `limit`, `kit_session_id`) are already documented in detail, including the default-vs-explicit behavior of `limit`. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

"Search Lady Whiskerdown's archive" names a specific verb and resource, which rescues the vague name ("recall") and title ("Finding things"). It does not explicitly contrast with others, though "use it first for anything Lady Whiskerdown should know" implicitly separates it from `remember`, `areas`, and `systems`.

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?

"Use it first for anything Lady Whiskerdown should know" gives a clear default-priority rule that tells an agent when to reach for this tool before others. It stops short of stating exclusions or naming the write-path sibling (`remember`) as the alternative for storing rather than retrieving.

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 carry only a title, so the description bears the disclosure burden and does add real context: this is a read, results are 'scoped to this key' (an access/visibility constraint), and the receiver endpoint returns no graph or entity enrichment. It does not cover failure behavior for a missing or foreign-key id, which keeps it from a 5.

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, both load-bearing, with scope stated first and the exclusion (no enrichment) second. Nothing is repeated from the name or title and no sentence could be dropped without losing information.

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

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

For a two-parameter fetch with a fully documented schema and no output schema, the description supplies the essential context: where the id comes from, that the result is the raw memory scoped to this key, and that no enrichment is applied. It stops short of indicating the memory's shape or not-found behavior, a minor gap given the absence of an output schema.

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

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

Schema description coverage is 100%, and the schema already documents both id (including the m#N and cross-Kit cite forms) and kit_session_id. The description only reinforces that the id originates from recall, adding no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read a single Lady Whiskerdown memory by id') and immediately scopes it against the sibling that produces ids ('as returned by recall'). It also rules out graph/entity enrichment, so an agent can tell this apart from recall or any enrichment variant without opening the schema.

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 intended workflow by tying the id to recall's output, which tells the agent to call recall first for discovery and use this for single-record fetch. It does not explicitly state when NOT to use it (e.g., batch reads or search), but the context is clear enough to select correctly.

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

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

With only a title annotation, the description carries the behavioral burden and does substantial work: it discloses that returned data is live and volatile ('it will change'), that answers should be timestamped, that results must not be persisted as memories, and that a child/subagent must wake with its own session. Gaps remain around failure modes, permissions, and whether calls are read-only against the external system.

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?

Purpose is front-loaded, but the prose is packed into long run-on clauses ('its own and those of Kits linked to it', 'recall first, then ask the system for the current figures') that force re-reading. Every idea is relevant, yet the same content could be structured as short mode bullets with far less parsing cost.

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 multi-mode gateway with a nested `arguments` object and no output schema, the description covers mode dispatch, ordering with recall, volatility, and session requirements. The notable omission is return shape — with no output schema, saying what a system listing or a tool run yields would help an agent plan the follow-up 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 coverage is 100%, so baseline is 3; the description exceeds it by explaining the dispatch chain the parameters form — bare call lists systems, `system` alone returns that system's tools and their arguments, `system` plus `tool` executes — which the schema only states piecewise. It does not add format details for `arguments` beyond deferring to the target tool's 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 states a concrete verb and resource: query live records held by connected business systems (accounting, HR, a shop), including systems of linked Kits. It also distinguishes itself from the sibling `recall` by contrasting 'history, decisions' with 'today's records'. The name 'systems' alone is vague, and the three modes (list systems / list a system's tools / run a tool) are only spelled out later, but the overall purpose is recoverable.

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 sequencing against a named sibling: 'recall first, then ask the system for the current figures', and says recall names the record to ask for. Mode selection is fully enumerated: nothing lists systems, `system` shows a tool's arguments, `system`+`tool` runs it. It also includes a negative instruction — never save the answer as a memory — which is exactly the when-not guidance an agent needs.

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 supply only a title, so the description carries the behavioral burden and does disclose meaningful traits: what gets returned, that there is no persona to adopt, that identity must be preserved and referred to in the third person, and that the session must be woken per-agent. It does not state side effects, idempotency, or whether a session is allocated server-side — a notable gap for a bootstrap call with zero safety annotations.

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

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

The imperative 'Call this first' and the payload enumeration are front-loaded, so the agent hits the critical instruction immediately. The host list (VS Code/Copilot, Cursor, Claude Code, Codex) is a dense enumeration that could be compressed, but every remaining sentence carries distinct information about identity handling or the recall alternative.

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

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

With no output schema, the description does the needed work by describing the shape of the response (identity, visible areas, permitted tools, keeper rules). Combined with the schema's session-ID guidance, an agent can call it correctly on first turn. The unexplained `scope` parameter is the main completeness hole.

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 only 50%: `kit_session_id` is documented in the schema itself (including the subagent rule) and the description adds nothing to it, while `scope` (work/personal/all) is neither described in the schema nor mentioned anywhere in the description. An agent cannot tell from either source what `scope` changes about the returned knowledge areas or tool list, and the description makes no attempt to compensate for that 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?

States a concrete action (open Lady Whiskerdown) and enumerates the return payload (`you_are`, visible knowledge areas, permitted tools, keeper rules), which tells an agent exactly what a bootstrap call yields. It explicitly distinguishes itself from `recall` and implicitly from `areas`/`systems` by saying those are reported here. The metaphor 'an archive you can question' is slightly loose, but the concrete payload list removes 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?

Gives an unusually explicit trigger: call first in every new chat, before the first substantive answer, across named hosts. It also names the alternative for knowledge lookups ('call recall first instead of using general model knowledge'). There is no explicit when-not-to-call guidance (e.g. mid-conversation re-wakes or repeat calls in the same session), which keeps it below 5.

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