RepoMemory

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

Annotations already declare this is a read-only, idempotent, non-destructive, non-open-world operation, and the description adds substantial behavior beyond that: returned content is truncated, full bodies require `recall` with an id, missing/unknown projects list account projects, and entries are notes rather than instructions.

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 primary instruction and then supplies necessary operational details about truncation and project fallback. It is slightly repetitive at the end with 'Free.' and 'Free to call.', which is wasted space.

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, but the description explains what is returned, how bodies are truncated, how to retrieve full entries, and what happens without a valid project. That is sufficient for an agent to call the tool 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 coverage is 100%, so the schema already documents both parameters. The description adds useful project semantics beyond the schema, including using the repository name from `AGENTS.md` or `CLAUDE.md` and the fallback behavior when `project` is omitted, though it adds little about the `recent` parameter beyond what its schema description already says.

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: it briefs the agent by returning active guardrails, open/claimed tasks, and newest entry titles. It clearly distinguishes itself from `recall`, which is for retrieving full bodies or focusing on the change at hand.

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 states explicitly to call this first at the start of a session before planning any change, explains where to get the project name, and describes the fallback when `project` is omitted or has no ledger. It also names the follow-up alternative: use `recall` for the change at hand.

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 non-readonly, non-idempotent annotations, it discloses the mutation semantics that actually matter: the claim_token must be retained, claims expire after `minutes` (default 120, crash-safe), re-claiming extends rather than duplicates, and a foreign claim is refused. This is exactly the extra context annotations cannot carry.

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?

Front-loaded with the purpose and the primary parameter, then ordered by workflow step (claim → extend → release → finish). Minor waste in the duplicated 'Free.' / 'Free to call.' tail, which is the only reason it falls short of 5.

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 six-parameter stateful mutation with no output schema, it still covers the return value ('task', or null when nothing is open), the token lifecycle, and the failure mode. Nothing an agent needs in order to call 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 already 100%, so the baseline is 3, but the description adds genuine meaning: omitting `id` selects the oldest open task, `claim_token` is required to extend or release despite matching `agent` names, and `minutes` governs expiry rather than being a mere timeout. It does not restate types, only intent.

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 ('Take a task') plus the reason for doing so (preventing duplicate work), and it explicitly separates itself from siblings by naming retire_entry as the completion step. An agent can distinguish it from record_entry/retire_entry without opening a 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?

It spells out when to call it (before starting work), what to pass or omit (id vs. oldest open task), how to extend, how to undo via release=true, and where to go when finished (retire_entry). The already_claimed refusal case and the 'your own name is not enough' caveat close the obvious ambiguity.

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?

Even with annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral detail: word matching prioritizes titles, retired entries are excluded by default, long bodies are truncated with body_truncated, id returns an entry regardless of status, notices flag instruction-like text, and missing ledgers return hint and known_projects.

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 purpose and usage, and nearly every sentence carries operational value. There is minor redundancy at the end with 'Free.' and 'Free to call.', but overall it remains dense and purposeful rather than 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?

There is no output schema, but the description explains the returned entries, fields, truncation marker, notice behavior, hint fallback, and omitted empty fields. For an agent invoking this tool, the description supplies everything needed to understand both how to query and what to expect back.

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 would be 3, but the description adds meaningful semantics beyond the schema. It explains how query terms are matched and weighted, how empty query behaves, how include_retired affects visibility, and that id overrides other filters.

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

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

The description opens with a specific verb and resource: search the project's ledger for decisions, attempts, and prohibitions. It clearly distinguishes recall from write-oriented siblings like record_entry and retire_entry by framing it as a retrieval tool for prior context.

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

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

It gives strong when-to-use guidance: before planning a change, removing code, or repeating an approach. Query construction is explained with concrete examples, and special cases like empty query, include_retired, kind filtering, and id lookup are covered. It does not explicitly state when to prefer sibling tools like brief, but the operating context 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?

The annotations only declare the safety profile (not read-only, idempotent, not destructive); the description adds substantial context beyond them: the idempotent-replay behavior costs no credits, successful calls cost 1 entry credit while failures are free, superseded entries are retired with a pointer, and bodies over 600 characters are echoed back as `body_truncated`. It also discloses an edge case — a newly created ledger triggering `new_project`/`known_projects`/`hint` in the response — which no structured field conveys.

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?

Front-loaded with the core instruction, then parameters, then return shape, then cost — a sensible order that lets the agent stop reading early. It is dense and every sentence carries information, but it is long enough that the return-shape and new-ledger details could be tightened slightly.

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 return contract itself and does so: entry id format (KNOW-n/TASK-n), truncation signaling, replay returns the existing entry, and the new-ledger result fields. Combined with cost and supersedes semantics, an agent has everything needed to call this correctly and interpret the result.

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 baseline is 3, but the description adds real meaning on top: it explains what belongs in `body` (what happened, why, what to do instead), that `agent` is for your name while the server separately records the key, and that `supersedes` retires the referenced entry rather than merely linking. The one gap is that `project` naming semantics are left to 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 opens with a concrete verb and resource ("Write down something... a decision, lesson, guardrail, note, or task") and enumerates the exact content types so the agent knows precisely what belongs here. It is clearly distinguishable from the listed siblings, which read (recall), delete (retire_entry), summarize (brief), and assign tasks (claim_task).

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 triggering conditions: record a lesson when a change is rolled back or a fix took digging, a decision when an approach is chosen over another. It also directs the replace-an-earlier-entry case to `supersedes`. What's missing is any exclusion or cross-reference — nothing tells the agent to check recall for duplicates first, or how this differs from retire_entry when retiring old data.

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 real context beyond the annotations: the effect is that recall stops returning the entry, the reason is required for everything except a finished task, and it returns the entry with its new status. The idempotency statement and "Free" duplicate idempotentHint and the read-only cost profile, which keeps it short of 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?

Front-loaded with the core action, alternatives, then effects and return value. Minor waste: "Free" appears in the body and again as a trailing "Free to call." line, and the idempotency note restates an annotation.

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, it covers effect on future recall, required reason semantics, idempotency, cost, and the return value (entry with new status). Nothing essential 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 baseline is 3, but the description adds meaning the schema does not encode: `reason` is required in practice for anything but a finished task, while the schema lists only `project` and `id` as required. That conditional requirement is genuinely useful beyond the structured 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?

States a specific verb (retire/mark done) and specific resources (decision, lesson, guardrail, note, task), and explicitly contrasts itself with record_entry with `supersedes`. An agent can distinguish it from every sibling without reading 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?

Explicitly covers when to use it (entry no longer true, task done), when to use the alternative (replacing an entry → record_entry with `supersedes`), and notes that repeated retirement is a no-op. This is the when/when-not/alternative pattern done fully.

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