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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is known. The description adds useful non-obvious scope context ('memory is not touched', project-level scoping), but it never states what happens to the tasks contained in a deleted group or whether the deletion is reversible — the most important behavioral question for a destructive tool.

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

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

Two short sentences, scope statement first and the non-obvious memory caveat second. Nothing is wasted and the critical information is 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?

A single optional param with full schema coverage and destructive annotations lowers the bar, and the memory caveat helps. Still, for an irreversible bulk delete the description omits the fate of contained tasks and any confirmation/irreversibility note, leaving a meaningful 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?

Schema coverage is 100% and the schema itself says 'Omit to clear every group'. The description restates the same semantics at a slightly higher level but adds no format, constraints, or examples 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?

States a specific verb (Delete) and resource (task groups), including both granularities: a single group or all groups in the project. 'Memory is not touched' cleanly differentiates it from memory-deleting siblings like forget.

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 two operating modes are implied by 'one task group, or all task groups of this project,' and the memory caveat hints at when a sibling is the better choice. However, no alternative tool is named and there's no guidance on prerequisites such as whether tasks in a group must be completed first.

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 disclose that this is a non-readonly, non-destructive, closed-world mutation. The description adds useful behavioral context that elapsed time is measured automatically, but it omits whether completion is idempotent, whether re-completing a finished task overwrites the prior result, or whether authorization constraints apply.

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 compact sentences, front-loaded with the action and outcome, and every sentence adds useful information: the done/failed distinction and automatic elapsed-time measurement.

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 four-parameter mutation with no output schema, the description covers the core outcome semantics and an automatic timing behavior. It remains incomplete about task_group, repeat completion behavior, and any side effects, so it is adequate but not fully sufficient.

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 75%, so the schema already documents result semantics, status enum and default, and task_id format. The description adds only a small amount by restating that 'result' holds the result or failure reason depending on status; the undocumented task_group parameter is not explained in either place.

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 ('Record the outcome of a task') and clarifies the two terminal modes (done with result, failed with reason). It is clearly a write operation, distinct from read-oriented siblings like get_task_status, but it does not explicitly name or contrast with any sibling.

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 implied: call this when a task finishes or fails, supplying its outcome. There is no explicit guidance on when not to use it, whether it can be called multiple times for the same task, or how it relates to siblings such as get_task_status or clear_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 this is a destructive, non-read-only mutation, so the safety profile is covered structurally. The description adds that omitting new_fact retires the fact, but does not discuss reversibility, invalid ids, or permissions beyond what the schema and annotations provide.

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 compact sentence front-loads the replacement action and follows with the retirement variant. There is no redundant or wasted text.

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 two-parameter destructive mutation with annotations covering destructiveness, the description covers the main behavioral choices and the id source. It leaves minor gaps around irreversibility and error behavior but is otherwise sufficient.

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%, with fact_id undocumented in the schema, but the description explains that fact_id comes from recall or what_do_i_know. It also explains that omitting new_fact invalidates the fact, adding useful meaning alongside the schema's own note.

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: replacing or retiring a fact, with the retirement mechanism stated. It references recall and what_do_i_know as the source for the fact id, but does not explicitly distinguish the tool from the sibling forget.

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 clearly states when to use it: for a wrong or outdated fact, or to retire one by omitting new_fact. It also points to recall and what_do_i_know for obtaining the id, though it does not explicitly say when to prefer forget over correction.

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, openWorldHint=false, destructiveHint=false, so the safety profile is partly covered. The description adds genuinely behavioral content beyond that: the consumption loop and the subagent execution model. It does not surface that the replace option overwrites a group that already has progress, which is the one risky behavior an agent should know about.

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, front-loaded with the creation action and input formats, then the workflow. No wasted 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?

For a 5-parameter mutation with no output schema, the description omits what is returned (group identifier? task list?) and whether the created group needs to be referenced later. The workflow hint helps, but return-value and replace-semantics gaps keep it at minimum-viable-plus.

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 60%, and the two undocumented parameters (markdown, tasks) are exactly the ones the description explains, including the '## Task 1: Title' heading format. It adds little about replace and system_prompt, which the schema mostly covers (replace) and leaves thin (system_prompt: 'Shared instructions returned with every task' is 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?

States a specific verb and resource ('Split work into ordered tasks' creating a task group) and names the two accepted input formats. It is clearly distinguishable from the task-consuming siblings (get_next_task, complete_task), which it references as downstream steps.

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 second sentence explicitly prescribes the follow-up workflow: loop get_next_task, do the task (ideally in a subagent), complete_task. That is strong usage context, though it never says when to choose this over alternatives like clear_tasks or which input format (markdown vs tasks array) to prefer in which situation.

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 readOnlyHint=false. The description adds valuable context beyond that: the operation is a soft retire, the entity and its relations stop appearing in searches, and the underlying data remains in the database. It does not address permissions, reversibility, or cascade limits, but the key behavioral trait is disclosed.

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 compact sentences with the operation and its effect front-loaded. Every sentence adds information without repetition.

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 soft-delete tool with no output schema, the behavioral explanation is solid. However, the complete absence of parameter semantics and any note on reversibility or permission requirements leaves meaningful gaps for correct invocation.

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

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

Schema description coverage is 0% for both parameters, so the description must compensate but does not. It never mentions the required 'name' parameter or the optional 'entity_type' enum, leaving the agent to rely entirely on raw schema types.

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 ('Retire') and resource ('an entity with its facts and relations'), making the operation's scope clear. It does not explicitly contrast itself with siblings like 'remember' or 'correct_fact', but the core 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?

Usage is implied by 'Retire an entity' and the note that it stops appearing in searches, but there is no explicit guidance on when to choose this over alternatives such as 'correct_fact' or 'remember'. No exclusions or prerequisites are 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?

The annotations declare the safety profile (readOnlyHint true, openWorldHint false), so the description's job is to add context, which it does: it discloses that long notes are clipped unless full is set and that results span project, branch, and PR. It does not mention ordering or token/size budgets, but the core behavioral traits are covered.

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 filler. The resource and scope come first, followed by the clipping caveat, so the agent front-loads the most decision-relevant 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?

There is no output schema, so the description should hint at the return shape, which it does: a list of recent notes, possibly truncated. It lacks detail on ordering and on whether task/issue entries are interleaved, but for a three-optional-parameter read tool this is close to sufficient.

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%, so the baseline is 3. The description reinforces the full-flag interaction with clipping but only restates the schema's 'first 600 characters'; the type parameter has no description in the schema and gets no explanation here beyond the enum values being self-descriptive.

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 specific resource (recent saved notes) and a precise scope: project-wide notes plus the current branch and PR. That scope statement separates it from generic memory lookups like recall or what_do_i_know, although the verb itself is only implied by the tool name.

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 never says when to call it rather than recall, what_do_i_know, or worklog, and it gives no exclusions or prerequisites. An agent must infer from the scope phrase alone that this is the lightweight 'what happened recently on this branch' lookup.

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 the mutation profile (readOnlyHint=false, idempotentHint=false), and the description adds real value on top: the 30-minute abandonment/retry rule is a non-obvious behavioral trait an agent could not get from structured fields. It does not cover failure behavior when no pending task exists, which keeps it below 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 tight sentences, zero filler, with the core action front-loaded and the exception rule second. Nothing could be removed 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 non-idempotent claim operation with no output schema, the description should say what comes back (task fields? an ID for later complete_task?) and what happens when the queue is empty. Neither is covered, leaving a meaningful gap for an agent wiring this into a workflow.

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 single task_group parameter already carries its own description ('Defaults to the latest group'). The tool description adds no additional semantics about what a group is or how selection interacts with the default, 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 — 'Claim the next pending task and mark it running' — which clearly distinguishes it from siblings like get_task_status (read status) and complete_task (finish work). It stops short of explicitly naming those siblings, so it doesn't reach the top band.

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 claim-based verb implies the worker-pickup use case, but the description never states when to use this versus get_task_status or complete_task, nor any preconditions (e.g., must a task group exist first). Usage is inferable but not guided.

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 openWorldHint=false, so safety is covered. The description adds that the per-task mode includes the result or error payload, which is genuine behavioral context. It does not disclose behavior for an unknown/expired task_id, task_group defaults beyond the schema note, or output volume.

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 front-loaded sentence stating the default behavior first and the task_id variant second, with zero filler. The semicolon split mirrors the two modes cleanly.

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, so the description must carry return-shape information, and it only sketches 'summary counts' and 'result or error' without detail. Error paths (missing task_id, unknown group) are unaddressed, leaving meaningful gaps for a two-mode 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 coverage is only 50%, and the description compensates for the undocumented task_id by explaining its effect: it switches from group summary to a full single-task record including result or error. task_group's default is already handled by the schema. Minor gap: no format/ID-source hints.

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 resource (task status) and both operating modes: group-level summary counts plus per-task status, or, with task_id, one task in full. It is clear what the tool retrieves, though it never names or contrasts sibling task tools like get_next_task or complete_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?

'with task_id, that task in full' gives a clear conditional for the two modes, which is useful. But there is no explicit when-to-use guidance versus the many sibling task tools (get_next_task, clear_tasks, complete_task), nor exclusions or prerequisites.

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 openWorldHint=false, so safety is covered by structured data. The description adds genuine context beyond that: what check enumerates (old low-importance entities, stale notes, file entities whose path no longer exists), which is the kind of behavioral detail an agent cannot get from 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?

Two sentences, no filler, and the default return content is front-loaded ahead of the conditional check behavior. Every clause carries 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?

With no output schema, the description correctly enumerates the returned metrics, which is the essential missing piece. Minor gaps remain: 'top entities' does not say how many or by what ranking, and the counts' scope (whole graph vs project) is unstated.

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 meaningfully expands 'check' beyond the schema's terse 'Also list cleanup candidates' by naming the actual cleanup categories. max_age_days is left entirely to the schema, which is acceptable given full 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 specific verb (counts) and resource (graph: entities, relations, facts, notes, orphans, top entities), and the 'With check' clause clarifies the extended mode. No sibling tool covers graph health, so it is unambiguously distinguishable.

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 'With check:' clause implies when to enable the extended mode, but there is no explicit guidance on when to call graph_stats at all versus other tools, nor any exclusions. Usage is left to be inferred from the name and the word 'health'.

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 idempotency, non-destructive, and non-readonly. The description adds useful behavioral detail: remove:true disconnects, it applies to all types unless relation is given, and the default relation is relates_to. It still doesn't say what re-linking returns or what happens to duplicate links, so it isn't exhaustive.

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, front-loaded with the primary action before the remove variant, and no wasted 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?

For a 7-parameter mutation tool with annotations present and no output schema, the description covers the key behavioral decisions. It omits what happens on repeated links and return behavior, but annotations and schema carry most of the remaining burden.

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 71%, and the description meaningfully supplements it: types are optional unless names are ambiguous, remove targets all relation types unless narrowed by relation, and relation defaults to relates_to. This adds real semantic value beyond the schema 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 uses specific verbs (connect/disconnect) and a clear resource (two existing entities), with a stated conditional (remove: true). It is distinguishable from all siblings, which handle memory, context, tasks, and graph stats rather than entity linking.

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 when types are needed ('only when a name matches more than one entity'), which is useful conditional guidance. However, it never addresses when to link versus other relationships or any prerequisites/exclusions, leaving usage largely implied.

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 openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: results are limited to projects with memory and sorted newest first, and the current project is auto-detected. It says nothing about pagination or result shape, but with annotations present a 3 is appropriate.

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 very short sentences with the scope and ordering front-loaded and no filler. The second clause ('the current project is detected') is slightly cryptic about who does the detecting, but it is efficient overall.

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

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

For a simple read-only listing tool with two optional, fully documented parameters and no output schema, the description covers scope, order, and when the call is unnecessary. Only minor gaps remain, such as what fields a project entry contains.

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%, with both 'limit' (default 20, max 100) and 'query' (key or path substring filter) documented in the schema. The description adds no syntax or filtering detail beyond that, so the schema is doing all the parameter work — baseline 3.

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 the resource (projects) and adds meaningful scope — only projects that have memory — plus ordering (newest first), which distinguishes it from a generic project listing. It doesn't restate a verb explicitly, relying on the name for 'list', but the scoping makes the intent 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?

'Rarely needed: the current project is detected.' signals that this tool is normally unnecessary because the current project is inferred, which is implied usage guidance. However, it never names the alternative (e.g., get_context) or states the condition under which listing is actually warranted, leaving the agent to infer it.

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 cover the safety profile (readOnlyHint true, openWorldHint false), and the description goes further by disclosing matching behavior — accent-insensitive, word-prefix and stem matching, parts-of-word fallback, and that it is not meaning-based. It also notes global facts are included, which materially affects result expectations. It stops short of describing result volume or ranking.

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 dense sentences, front-loaded with what the tool returns and followed by matching semantics and usage advice; every sentence carries information. The 'Start work with this' directive would land better at the front than buried at the end, but nothing is wasted.

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 search tool with no output schema, the description adequately characterizes the return shape (entities with dated facts, related entities, notes) and the matching model an agent must understand to get useful results. Only the entity_type filter remains unexplained, a minor gap in an otherwise self-sufficient definition.

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

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

With only 50% schema coverage, the description does compensate for the undocumented required 'query' parameter by explaining how to formulate it (words, synonyms, both languages). However, the 'entity_type' parameter with its eight enum values is never addressed, and the relationship of 'all_projects' to the stated 'Includes global facts' scope is left implicit.

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 specific verb and resource ('Search memory by keywords') and spells out what the result set contains: graph entities with dated facts, linked entities as related, and matching notes, plus global facts. It does not explicitly differentiate itself from plausible siblings such as what_do_i_know or get_context, which keeps it off a 5.

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 entry-point guidance ('Start work with this') and explains the query strategy needed because matching is lexical, not semantic ('search with the words, synonyms and both languages the facts would use'). That is actionable context, though no explicit 'use X instead when Y' routing against the sibling tools is provided.

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

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

With annotations only declaring the safety profile (not read-only, not destructive), the description supplies the real behavioral context: existing entities are extended rather than replaced, duplicates are skipped, entity names appearing in facts are auto-linked, and contradictory facts surface as possible_conflicts. That last point is valuable output-shape information absent from annotations. It stops short of stating permission or size-failure behavior beyond the 1000-character limit.

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

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

A single front-loaded paragraph that opens with the core action and then layers constraints and side effects. Every sentence carries a distinct constraint or behavior; only the scope sentence could arguably be folded in more tightly.

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 mutation tool with no output schema, the description covers merge semantics, deduplication, conflict reporting, auto-linking, size limits, and scope meaning, which is most of what an agent needs. The absence of any mention of summary or entity_type semantics is the remaining 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?

Schema coverage is 57%, so the description needs to compensate for gaps and partly does: it constrains observations (one fact per item, under 1000 characters), explains keywords as search vocabulary because search has no semantic matching, and defines the 'global' value of scope. The name parameter's brevity is mentioned but summary and entity_type receive no description-level clarification.

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: create or update a knowledge-graph entity and add facts to it. The create-or-update semantics are spelled out (existing name extended, duplicates skipped), so the agent knows exactly what the call does. It does not differentiate itself from siblings like save_memory, correct_fact, or link, which keeps it from a 5.

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 operative guidance within the tool: one fact per item, keep names short, add keywords so search finds it later, and use scope 'global' for user facts that span projects. However, it never says when to pick this over save_memory, correct_fact, or link, so the alternative-selection gap remains.

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

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

Annotations only declare readOnlyHint=false with destructiveHint=false; the description adds the crucial lifecycle detail that a proposed rule is queued and requires user approval in the panel, web page, or CLI rather than taking effect immediately. It also flags a safety exclusion (no secrets). It stops short of saying what 'show' returns or how approved rules affect later sessions.

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?

Four sentences, front-loaded with what the resource is before the action semantics and the exclusions. Dense but no filler; the 'action show ... action propose' parallel is easy to scan. Slightly compressed phrasing ('as injected at session start') takes a moment 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?

With no output schema, the definition still conveys the propose workflow, approval step, and scope of the rule set, which is what an agent needs to choose an action. It never says what 'show' returns (full list, per-scope breakdown, formatting), which is the one real gap for a read action with no 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 coverage is 80% and the schema already documents scope semantics, mode default, text length, and reason. The description only ties action values to outcomes ('show' returns them, 'propose' queues), adding little on scope or mode beyond the enum descriptions. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Names the resource precisely ('the user's standing rules for this project, organization and device') and enumerates the two verbs via action values: 'show' returns them, 'propose' queues a new rule. It also distinguishes the tool from the nearby sibling by name ('Preferences ... go to the taste tool instead'), so an agent can route 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?

Explicit when-to-use conditions: propose only for 'a rule the user explicitly asked to make standing'. Explicit when-not and alternatives: conversational preferences go to the taste tool, and 'Never propose secrets or one-off instructions'. This is the strongest dimension of the definition.

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 this is a non-destructive, non-open-world write, so safety is covered. The description adds the qualitative nature of what lands in storage (narrative session note vs durable fact), which is genuinely useful. It doesn't say whether notes are later retrievable via recall/what_do_i_know or how they interact with correct_fact/worklog, so a 3 is right.

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

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

Two short sentences with zero waste, and the core purpose comes first ahead of the sibling disambiguation. Nothing to trim.

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, single-required-field write tool with annotations and no output schema, the definition is nearly sufficient. The one missing piece is the read-side pairing — telling the agent that saved notes surface through recall/what_do_i_know — which would close the loop with a very crowded sibling set.

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 explains tags, type, scope, title and content; baseline 3 applies. The description adds only a loose mapping from 'done, decided or found' to the type enum values, which is marginal but nonzero added meaning.

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

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

States a specific verb and resource ('Save a session note') and defines the payload semantically ('what was done, decided or found'). It also names the sibling it is not (remember), so an agent can separate the two note-writing tools without reading either 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?

Gives an explicit routing rule: 'Use remember for durable facts; use this for narrative.' That names the alternative and the condition that selects it, which is exactly the decision an agent has to make among the memory siblings. The only gap is that it doesn't mention which tool reads these notes back (recall/what_do_i_know), but the write-side choice is fully covered.

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 non-read-only, idempotent, non-destructive, closed-world. The description adds the trait annotations cannot express: the override applies "for this session" and is normally unnecessary because scope is auto-detected. It does not say whether the override can be cleared or how it interacts with later detection, a minor remaining 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?

Two sentences, front-loaded with the action and scope, followed immediately by the deferral guidance. No filler and nothing duplicated from the structured fields.

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-optional-parameter session setter with no output schema, the description supplies the essential mental model (detected by default, override to correct). It leaves unaddressed whether the override persists across sessions or how a partial override merges with detected values.

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 80%, so the schema already documents pr, project and project_name; the description only restates that project/branch/PR are the settable dimensions. It adds no guidance on project_name vs project_path or which fields drive detection, and branch carries no schema description at all.

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?

Uses a specific verb ("Override") plus the exact resource scope ("project, branch or PR for this session"), which is far more informative than the bare name. It implicitly complements the sibling get_context (read) by being the write/override counterpart, though it does not name any sibling 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?

Explicitly states the default path (auto-detection from the working directory) and the narrow condition for calling it: "call it only to correct the scope." That is a clear when-to-use/when-not signal, short only of naming an alternative tool by name.

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, destructiveHint=false and openWorldHint=false. The description adds real context beyond that — preferences are injected at session start and apply immediately with no approval — which is the key behavioral trait an agent needs. It also states a hard constraint against storing secrets or private data. It does not describe what happens to existing entries when a rule is replaced or dropped, so depth is moderate.

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 identity before action and scope detail, and nearly every clause carries operational information. It runs long and mixes several concerns into single sentences (the learn action list is dense), but there is little true 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?

With no output schema, the description covers what show returns (a list with ids) and covers the mutation model, scope levels, and content rules for learn. For a 3-parameter tool with one required enum, an agent has enough to invoke it correctly. Edge behavior on replace/drop of existing entries is the only notable omission.

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%, and the description fills the meaningful gaps: it defines what each learn action value means, explains scope as global vs org vs project, and instructs how to phrase the rule field ('general, short instruction, one step more general than the message'). That is genuine added meaning over the enum in the schema. The maxItems cap and id-on-forget detail 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?

Opens with a specific framing — a learned preference store covering style, workflow, wording, tools — and enumerates the three actions (show/learn/forget) with what each does. An agent can tell this holds durable user preferences. It doesn't explicitly distinguish itself from sibling memory tools like save_memory, remember, or rules, which keeps it from a 5.

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 a concrete trigger: 'call learn when the user asks you to remember how they want something', and clarifies that in Claude Code the panel learns automatically. The learn sub-actions (new/reinforce/refine/replace/drop) each carry a plain-language condition. It stops short of telling the agent when to prefer this over save_memory or remember.

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 openWorldHint=false, so safety is covered. The description adds real value with the two-hop traversal boundary, which bounds cost and result size, but says nothing about behaviour when the entity is missing or how the traversal is capped.

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 dense sentence that front-loads the resource ('one entity') and enumerates the return contents, with zero filler. Slight gap: an opaque tool name that the description never echoes or clarifies.

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 (facts, relations, neighbours) which is a genuine plus. However, for a two-parameter lookup tool with zero schema coverage, the omission of any parameter meaning or not-found behaviour leaves it only minimally 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 0% and the description never mentions the parameters. It does not say whether name must be exact or case-sensitive, nor what entity_type disambiguates (the enum values suggest it narrows the lookup, but this is unexplained).

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 exactly what the tool returns: dated facts, direct relations, and neighbours up to two hops for a single entity. Scope and depth are precise, though it lacks an explicit verb and never distinguishes itself by name from siblings such as recall or get_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?

There is no guidance on when to use this versus recall, get_context, or rules. The agent must infer that this is the deep-lookup tool while recall is presumably a lighter search, and there are no stated preconditions or 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the data source (session transcripts, not a timesheet DB) and non-obvious computation semantics: agent time sums across parallel sessions while wall time counts each minute once. Those are exactly the details that change how an agent interprets the numbers, and they are not derivable from any structured field.

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, front-loaded with what is measured, then the data source, then the intended use, then the two time-accounting rules. Every sentence carries distinct information and nothing is repeated from the schema.

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 five optional parameters, no output schema, and safety already covered by annotations, the description supplies the essential model: measurement unit, grouping, source, and the agent-vs-wall-time distinction. What it omits is the shape of the returned report (fields per task, how totals are grouped or sorted), which an agent must infer despite there being no 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%, so range/from/to/detail/project semantics are already documented in the schema itself. The description only adds the implicit grouping notion ('per project and task') and the period framing; it contributes no extra format, precedence, or defaults beyond the schema. 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?

The description states precisely what is measured (time worked by the user and the agent), at what granularity (per project and task, i.e. branch or ticket), over what scope (a period), and from what source (session transcripts). No sibling tool overlaps with time reporting, so no explicit differentiation is needed, though the phrasing is a resource statement rather than a verb+resource construction.

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 two concrete example questions that select this tool ('how much time did I spend on X this week', 'what did I do this week'), which makes the intended call context unambiguous. There are no exclusion rules or named alternatives, but none of the sibling tools compete with this capability, so the guidance is practically complete.

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