ctxkeeper

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds real behavioral context: the output is budgeted, includes path:line citations, and may include memories. It does not mention what happens when the budget is exhausted or how results are ranked/truncated, so it stops short of full disclosure.

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 tight sentences, front-loaded with what the tool returns and followed by the when-to-use cue. Every clause carries information; nothing is redundant.

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?

There is no output schema, and the description does its part by characterizing the return value (excerpts with citations and memories). However, for a 4-parameter tool with three undocumented parameters, an agent still lacks the knobs' semantics, so the definition is not fully 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 only 25% — only `query` is documented. The description never explains `max_files`, `budget_tokens`, or `include_memories`; "token-budgeted" hints at budget_tokens but gives no defaults, bounds, or effect. It fails to compensate for the low 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?

States a concrete verb and resource: returns a token-budgeted pack of relevant code excerpts with path:line citations plus matching project memories. That is far more specific than any sibling, but it never names a sibling (e.g. project_brief or recall) to contrast against, so the differentiation is implied rather than explicit.

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 clear positive guidance: "Use this BEFORE broad greps or reading whole files." It explains the tradeoff (token use and round trips). It does not say when not to use it or how it relates to recall/project_brief, which is the remaining gap.

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 already declare destructiveHint=true and idempotentHint=true, so the safety profile is carried structurally; the description earns credit for adding the crucial behavioral fact that the operation is reversible via restore=true with the same ID, and that archived items drop out of briefs and recall. It does not address behavior when the ID is unknown or invalid.

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, each doing distinct work: effect, reversibility, and trigger. The most important information (what it does and its effect) is front-loaded with no 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 3-parameter mutation tool with no output schema, the description covers the main path and the undo path, but never explains what scope controls or what happens if the ID doesn't resolve. An agent could call it correctly on the happy path but would guess on scope.

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 67%: id and restore are documented in the schema, and the description usefully reinforces the restore semantics. However, the scope parameter (all/project/global) is undocumented in both schema and description, leaving a required piece of invocation semantics unaddressed.

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 specific verb and resource ("Archive a memory by ID") plus the observable effect ("stops appearing in briefs and recall"), which distinguishes it from sibling tools like recall and remember. It is clear about what the tool does, though it doesn't explicitly name sibling alternatives to route away from.

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 when a decision is superseded or a note is wrong" gives a concrete trigger condition, and the restore sentence explains the reverse path. There is no explicit statement of when *not* to use it (e.g. when to prefer remember or recall), so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description's 'append' wording is consistent with a non-idempotent, non-destructive write. It adds useful context (timestamped, short, session-handoff purpose) but says nothing about where entries land, whether they are retrievable via recall, or whether repeated calls duplicate entries.

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 padding, with the action and its content shape front-loaded before the trigger condition. 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?

For a 6-parameter write tool with no output schema and sparse schema descriptions, the definition covers purpose, trigger, and most content fields adequately. Gaps remain around `duration_min`, entry persistence/retrieval, and what the call returns, but nothing critical to invoking 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 description coverage is only 17%, with just `summary` documented, so the description carries real weight here: it names files, commands, outcome, and next steps, mapping meaning onto four otherwise undocumented parameters. Only `duration_min` goes unmentioned, and no format or limit details (maxItems, enum values) are supplied.

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 ('append') and resource ('work-log entry') and enumerates the entry contents (what changed, files, commands, outcome, next steps). It is clearly a write-to-log operation, though it never contrasts itself with the memory siblings (remember/recall/forget) that an agent might confuse it with.

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 explicit timing guidance: 'Call this before ending a session so the next agent can resume without re-reading everything,' which tells the agent exactly when to reach for it and why. It does not name an alternative tool or state when not to use it, so it stops short of full routing 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 already establish readOnlyHint and idempotentHint, so safety is covered; the description adds that the output is token-budgeted and substitutes for exploratory reads, which is real behavioral context. It omits the 30s caching behavior and scan cost, though the schema's refresh param hints at it.

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, imperative opener first, then a packed content list. Every clause earns its place and nothing is padded.

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 carries the burden of describing return content, and the enumerated section list does that well. It could say more about output shape (structured vs prose) or how budget_tokens truncates sections, but an agent has enough to call 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?

Schema description coverage is 100%, so both refresh (30s cache override) and budget_tokens (400–8000, default 1200) are already documented in the schema. The description adds no parameter meaning beyond noting the brief is "token-budgeted"; 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?

"Start here" plus a concrete enumerated payload (detected stack, run/test commands, files to read first, git state, TODOs, decisions, gotchas, logs) states the verb and resource precisely. It distinguishes itself from siblings like recall/context_pack by framing the output as a synthesized session-start brief rather than a lookup.

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?

"Start here" and "at session start" give a clear triggering condition, and "replaces exploratory file reads" tells the agent what to skip. It does not name when NOT to use it or which sibling to prefer for follow-ups (recall, context_pack), so it stops short of full routing 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 already declare readOnlyHint and idempotentHint, so safety is covered. The description adds real behavioral context beyond that: the ranking is a blend of keyword match across specific fields plus importance and recency weighting, which tells the agent why result order may not be pure keyword relevance. It omits nothing critical for a read tool, though it says nothing about result volume/pagination 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 compact sentences, front-loaded with the core action and ranking model. The middle 'Filter by type, tag, or scope' sentence largely restates the schema's enum fields, but it is short enough not to be wasteful.

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

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

For a 7-parameter tool with near-zero schema description coverage and no output schema, the description covers the search model and filters but leaves limit, include_done, and include_archived unexplained — notably the default exclusion of done/archived entries. Adequate to call correctly, but not 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 only 14% across 7 params, so the description has to compensate. It does explain the query semantics (keywords, CJK-aware) and the type/tag/scope filters, but says nothing about limit, include_done, or include_archived — the last two being defaults that silently hide todo and archived memories, a behavior an agent should know about.

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 ('Search saved memories') plus the ranking model (keyword/CJK-aware, title/tags/files/content, importance and recency weighted), which an agent can distinguish from the write-oriented 'remember' sibling. It stops short of explicitly contrasting with siblings like project_brief or context_pack, but the action is 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?

'Use before asking the user to repeat context' gives one concrete triggering situation, which is genuinely useful. However, there is no guidance on when not to use it or which sibling (project_brief, context_pack, status) to prefer for related retrieval needs, leaving alternatives to inference.

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 already declare write (readOnlyHint=false), idempotent, non-destructive, and the description usefully adds the mechanism behind idempotency: "Identical entries are deduplicated." It also discloses that entries land in a local project store unless scope is global. It does not say what a caller gets back or how deduplication resolves (silent skip vs. error), which keeps it off 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 sentences, both load-bearing: the first establishes what is written and where, the second establishes when to write. The dedup note is a single trailing clause rather than its own paragraph. Nothing is repeated or padded.

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 9-parameter write tool with no output schema, the description covers purpose, storage scope, triggers, and dedup behavior, which is most of what a caller needs. It omits how a caller obtains the ID required by `replaces`, and it leaves the relationship to `recall`/`forget` implicit, which is a genuine gap for a memory system with sibling tools.

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 78%, so the schema already documents most of the 9 parameters, and the description's enumeration of types and the project/global distinction largely restates the enum values. It adds no extra semantics for tags, files, importance, source, or replaces beyond what the schema descriptions provide. Baseline 3 is the right ceiling here.

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 a concrete verb (persist) and an enumerated resource set (decision, gotcha, fact, command, todo, note) plus the store it lands in, so an agent immediately knows what the tool does. It falls short of a 5 because it does not distinguish itself from the `todo` sibling even though it accepts a "todo" type, leaving a real ambiguity unaddressed.

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 this whenever the user states a preference, you make a non-obvious choice, or you discover something future sessions should know" gives three explicit, checkable triggers. It stops short of the top score because it never names alternatives or exclusions — nothing says to use `recall` to look things up, `forget` to remove, or `todo` for tracked tasks.

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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that this is a diagnostic/passive inspection tool rather than a data operation, but says nothing about output format, cost, or whether it touches the filesystem or git subprocess in ways that could be slow.

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

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

Two sentences: the first front-loads the reported contents, the second the usage triggers. No filler, no restatement of 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 usefully enumerates what the response contains, which is the key information an agent needs to decide to call it. Minor gap: it doesn't signal the response shape (structured JSON vs. human-readable text) for parsing purposes.

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?

Zero parameters, so there is nothing to document; the schema is trivially complete. Baseline 4 applies, and the description correctly implies a no-argument call.

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 ("Show") and then enumerates exactly what is reported: project root, store paths, memory/todo/worklog counts, git state, and limits. This is clearly distinguishable from every sibling (remember/recall/forget/todo/log_work), which all operate on memory data rather than reporting server state.

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

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

Gives two concrete triggering conditions: server setup and debugging why nothing is recalled. It doesn't name alternatives or state when not to use it, but for a zero-parameter diagnostic tool the selection guidance is clear.

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

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

Adds genuine context beyond the annotations: todos persist across sessions and surface in project_brief, which is the key behavioral property of this store. However, it is silent on the mechanics an agent would want for a mutable 8-param tool — how list is bounded (limit defaults to 30, max 100), whether duplicate titles are rejected, and what done actually does to the record.

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 compact sentence-per-action block, front-loaded with the resource and then the action contract. Every clause carries either a required-parameter rule or an alternative, with no padding.

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 4-action, 8-parameter mutation tool with no output schema and thin annotations, the description leaves too much open: list's return shape and pagination, the meaning of tags/content/importance, and whether reopening restores prior state. An agent could call the wrong action with the wrong parameters and only discover it from errors.

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 only 25%, and the description covers just the two that already have schema text (title, id) plus include_done. Four parameters — tags, limit, content, importance — are undocumented in both schema and description, including the limit that governs list output size and the importance score that presumably affects ordering.

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 ("Manage the durable project todo list") and enumerates the four supported actions with their semantics. It is distinguishable from the memory siblings (remember/recall/forget) by the 'project todo' framing, though it never names them explicitly.

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

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

Gives per-action conditions (title for add, id for done/reopen, include_done for list), which is real routing guidance within the tool. It stops short of saying when to use this versus remember/forget/context_pack, so an agent must infer the boundary between durable todos and memory entries.

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