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

The annotations already flag a non-read-only, non-idempotent, open-world write, and the description usefully adds the SSRF guard (private/loopback addresses rejected) and the return value (the new note's id). It does not explain what happens on repeated calls or content-extraction failures, but the security constraint is meaningful context beyond the 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 compact sentences with zero waste, front-loading the fetch action and its security constraint before the return value. 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?

With no output schema, the description compensates by stating the return value (the new note's id) and the write semantics. Combined with the fully documented schema, an agent has enough to call it correctly, though failure/retry behavior is unaddressed.

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 the schema already fully documents url, project, and session. The description adds nothing about parameter formats or defaults, so the baseline of 3 applies.

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

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

The description states a specific verb+resource pair: fetch a web page and save its readable content as a note. This clearly distinguishes it from siblings like notes_create or memory_write, which do not fetch external content. It stops short of naming a sibling explicitly, so it is clear but not maximally differentiated.

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 explains what the tool does but offers no explicit when-to-use versus alternatives (e.g., when to prefer notes_create for pasted content). No exclusions or preconditions are stated beyond the SSRF guard. Usage is only inferable from the verb.

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 mutation (readOnlyHint=false), idempotency, and non-destructiveness. The description adds real context beyond that: the flag lives in frontmatter for memories/notes, and starring never bumps the item's updated time — a side-effect disclosure that matters for an idempotent mutation. It does not cover permissions or how non-file kinds (project, plan, task, session, trial) persist the flag.

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

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

Three sentences, action front-loaded, each carrying distinct information (what it does, why it matters, how it is stored). No filler or restatement of the name.

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 and a mutating tool, the description adequately covers effect, storage mechanism, and a key side effect (updated time unchanged). It leaves open where the flag is stored for non-file kinds and whether any permission or scope rules apply, which is a minor but real 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%, so every parameter including the enum and the session/project scoping rules is already documented in the schema. The description only touches parameter semantics indirectly by explaining frontmatter storage for the memory and note kinds; 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 pair (star/unstar) and resource (item), and enumerates the effects. No sibling tool performs favoriting, so it is unambiguously distinct from memory_write, notes_update, tasks_update, and the rest of the list.

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 explains what favoriting achieves (console sort order, session-briefing pinning, recall rank boost), which implies when an agent would want it, but it never states when to use this versus leaving an item unfavorited or naming any alternative approach. Usage is inferred rather than directed.

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, idempotentHint=true, and readOnlyHint=false, which covers the safety profile. The description goes further by itemizing what each apply branch destroys or rewrites (retire, supersede, parent, retag) and by stating both rejection modes are reversible by the owner from the console. It does not describe the response payload or any permission/rate constraints, so it adds real context but not a full behavioral picture.

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

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

Purpose and the action=apply enumeration are front-loaded and every clause carries distinct information, but the apply enumeration is a single ~150-word parenthetical run-on with semicolon-separated clauses, which makes it harder to scan than a short bulleted list would be. Sized appropriately for the decision complexity; slightly dense in presentation.

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-value burden and partially meets it by naming the 'settled' field and the reason recorded there. It covers the important edge cases (inactive memory, reversibility, dismiss vs hide recurrence) but does not describe the full response shape or what a successful apply returns.

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 substantially enriches the action enum beyond the schema's one-line gloss by spelling out the effect of every apply sub-case, the inactive-memory override, and the permanent-vs-temporary distinction for dismiss/hide. It adds nothing for id or session beyond what the schema already states.

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 opening sentence names a specific verb+resource ('Resolve a gardener proposal') and immediately scopes it against the sibling gardener_proposals (which lists rather than resolves) and gardener_split. An agent can tell what this tool does and how it differs from its nearest siblings 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?

The description explicitly guides the apply/dismiss/hide choice, including the decision rule 'Prefer dismiss unless the suggestion is wrong in principle rather than wrong for now,' and contrasts the recurrence behavior of dismiss vs hide. It also documents the fallback path when the underlying memory went inactive, so no branch is left 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 readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' is restated structured data and earns no credit. What the description does add is the taxonomy of what a pending proposal can contain, which is genuine behavioral context about the payload, but it says nothing about ordering, volume, pagination, or whether applying is reversible.

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: the verb+resource landing in the first four words, and the read-only/routing sentence closes it. The middle parenthetical is long, but each clause defines a distinct proposal kind rather than padding, so it carries information density without much waste.

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

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

For a zero-required-parameter read-only list tool with no output schema, the description covers what is returned conceptually (the set of proposal kinds) and what to do next. It omits return-shape details such as ordering or whether results are paged, which is the only notable gap and a modest one at that.

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 prose parenthetical explains the meaning of nearly every value in the 'kind' enum (merge/consolidate duplicate memories, archive stale memories, reproject, rekind, ship_plan) beyond the schema's bare enum list, adding real semantic value for the main filtering parameter.

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 ('List pending gardener proposals') and then enumerates the heterogeneous proposal kinds an agent will actually see (merge, archive, digest, reproject, split, abandon_plan, etc.), so the name's abstract noun 'proposals' is concretized. It also implicitly separates itself from the write-side siblings (gardener_apply, gardener_request, gardener_split).

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 clear workflow: 'Review, then apply, dismiss or hide each with gardener_apply', naming the follow-up tool and the three actions available on each item. It does not state when to prefer gardener_request or gardener_split over this tool, but the review-then-act funnel is explicit.

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?

Crucially discloses it NEVER mutates memories despite readOnlyHint=false, explains the pending-proposal workflow (review then resolve), the splitSource guidance return, and the LLM chat client dependency. This adds substantial context beyond annotations, which only say it is non-destructive but not write-idempotent.

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 purpose and rich examples, but the parenthetical examples are dense. Every sentence earns its place, though slightly long.

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?

Complete for a proposal-generating entry point: covers what it does, what it does not do (mutate), how to proceed downstream, ambiguity handling, and the runtime dependency.

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 parameters are fully documented in the schema. The description adds the natural-language framing of 'request' but no format or syntax details 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 (reorganizing memory) plus the primary entry-point role, and enumerates five concrete operations with examples (fold, retire, synthesize, move, reclassify). Clearly differentiated from siblings like memory_write and gardener_split.

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 ('use this whenever the user describes how they want their knowledge organized'), when to pause ('if the intended change is ambiguous, ask a clarifying question'), and routes to alternatives (gardener_proposals, gardener_apply, gardener_split with the splitSource return).

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 write/non-destructive/non-idempotent (readOnlyHint=false, destructiveHint=false), and the description adds substantial context beyond them: it only creates reviewable pending proposals, produces one 'split' setup plus one 'reproject' per memory under plan 'split-<source>', never creates a project or moves a memory, and requires an LLM chat client plus a known source slug.

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-loads the core action and example, then the routing/behavior/requirements. Dense but every sentence carries operational content; it could be tightened slightly (the console retarget aside) but nothing is 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?

There is no output schema, but the description compensates fully by describing what is produced (pending proposals under a named plan) and the required follow-up review/apply steps, plus prerequisites and the session requirement. An agent has everything needed to invoke and interpret the call.

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

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

Schema coverage is 100%, so the schema carries the per-parameter burden (baseline 3). The description still adds value by pointing to project_list as the way to obtain the required source slug and by framing what instruction does ('which children, what stays shared') in workflow terms.

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 with concrete scope: 'divide one existing project into two or more NEW child projects, keeping cross-platform memories in a shared parent.' The worked example (arctop-app → arctop-ios + arctop-android) makes the operation unambiguous and distinguishes it from project_create ('NEVER creates a project').

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 says when to use it ('when the user wants to break one project into several') and how it is reached ('gardener_request points you here via splitSource'). It also names the downstream flow: review with gardener_proposals, then apply with gardener_apply — routing to the correct siblings with conditions.

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 and idempotentHint=false, so the agent knows this mutates and repeats accumulate. The description usefully adds that the id is preserved, but omits what happens when the memory does not exist, whether it appends to the end, and the fact that repeated calls duplicate content (relevant given non-idempotency).

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-loading the operation and the id-preservation behavior, followed immediately by the alternative. Zero 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 non-destructive mutation with no output schema, the description covers the operation, the state outcome (id retained), and the create alternative, while the schema fully documents parameters and annotations cover safety. Only edge-case behavior (missing memory, duplicate appends) is left 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 description coverage is 100%, so the schema already documents name, body, project resolution, and session scoping in detail. The description adds nothing beyond that, which is the correct baseline when the schema carries the parameter burden.

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 (an existing memory's body) plus a behavioral fact (the memory keeps its id), which distinguishes it from the create path. An agent can contrast this with memory_write without opening 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?

Explicitly routes the create case to memory_write, so the primary when-to-use boundary is stated. It does not address other adjacent siblings such as memory_edit or notes_append, leaving some selection work to the agent.

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 declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them by explaining exactly what destruction means here (file removed plus index row removed, no provenance, nothing left pointing at the old memory) and contrasting it with the soft-removal semantics of supersedes. That is precisely the context an agent needs before an irreversible call.

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 action and its consequence before any alternatives, and every subsequent sentence carries a distinct routing rule rather than restating the same caution. Length is justified by the irreversible nature of the operation.

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 destructive, three-parameter mutation tool with no output schema, the description supplies the missing pieces: irreversibility, what exactly is destroyed, and the preferred alternatives. Nothing an agent needs to call this safely is left 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 description coverage is 100%, so name, project, and session are already documented in the schema, including the session scoping rules. The description only echoes 'by name' and adds no format, naming, or scoping detail 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?

States a specific verb and resource ('Delete a memory by name') and immediately characterizes the mechanism's effect: the markdown file leaves the disk and its index row goes with it. The phrase 'with no provenance and no pointer left behind' distinguishes it sharply from memory_write with supersedes and from the gardener archive path.

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-not guidance ('Prefer nearly anything else') followed by named alternatives with the conditions that select them: memory_write/supersedes for wrong knowledge, gardener archive for stale knowledge, delete only for mistakes like duplicates or tests. This is the strongest form of sibling routing.

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, idempotentHint=true, readOnlyHint=false, so the safety profile is covered; the description does not contradict them. It does add real behavioral context beyond annotations: all-or-nothing atomicity ('all edits apply together or none do'), failed match changes nothing, and the return value (a unified diff plus content_hash). Since annotations carry the safety information, this is supplemental rather than load-bearing, so a 3 fits.

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-loads the core purpose and the search/replace mechanism, then routes to memory_write. The volume is high for one tool definition, but nearly every sentence carries routing or constraint information; only the parenthetical about memory_write requiring a body is arguably 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?

No output schema exists, and the description compensates by stating the return value (unified diff plus new content_hash). With 8 parameters, a destructive annotation, and metadata-only behavior all addressed, an agent has everything needed to call the tool 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 description coverage is 100%, so the baseline is 3 and the schema already documents old_string/new_string/replace_all/expect_hash. The description does add cross-parameter semantics the schema cannot express: sending description/tags_add/tags_remove with no edits leaves the body untouched, and tags_remove is the only way to clear a tag. That is meaningful value beyond the per-field docs.

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 ('Edit an existing memory in place with exact search/replace') and immediately differentiates the tool from memory_write by mechanism and cost ('instead of resending its whole body'). An agent can distinguish it from every sibling 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?

Gives an explicit routing rule: corrections that do not change what the item CLAIMS (typos, formatting, stale paths, status flips, metadata) go here; changes in MEANING go to memory_write with supersedes. It also names a case where this tool is the only option (metadata-only edits, clearing a tag), which is precise when-to-use guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuine context beyond them: the name-lookup falls back to a global memory of the same name, and reads are restricted to Seamless memories only. It omits return shape and error behavior on a missing name, so it is not 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 sentences, both front-loaded with the primary behavior and the most likely misfire (treating a local MEMORY.md entry as a Seamless memory). No filler or restatement of the name.

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 read-only tool with no output schema, the description covers access modes, scope, and the local-file distinction, which is what an agent needs to call it correctly. It does not describe the returned memory's shape or what happens when neither name nor id resolves, a minor 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 description coverage is 100%, so all four parameters (id, name, project, session) are already documented in the schema; the baseline is 3. The description echoes the name-or-id duality but adds no format or scoping detail beyond what the schema states, and never touches project/session.

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 (read) and resource (memory) with two distinct access modes (by name, with global fallback; or by id). It also draws a sharp boundary against a common confusion, distinguishing Seamless memories from client-side MEMORY.md files, so an agent can tell it apart from recall, memory_append, and file tools.

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

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

Gives clear selection context: use a name with project scoping/global fallback, or bypass resolution with an id, and redirects local auto-memory files to file tools. It stops short of explicitly contrasting with the sibling 'recall' tool, which is the most likely alternative for retrieval.

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 declare it is a non-readonly, idempotent, destructive write. The description goes well beyond that: update-in-place with a stable id, an advisory similarity hint on new names, the hint being withheld in fenced projects while the write still lands, supersession marking a memory invalid but keeping it readable, and partial-failure semantics where a failed supersede still leaves the new memory written. This is exactly the failure-mode and side-effect detail 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 core verb+resource and the notes_create boundary before descending into edge cases. It is dense but each sentence covers a distinct behavior (update-in-place, hint, fencing, supersede, retry); slightly long, but almost 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?

With no output schema and 8 parameters, the description carries the burden and does so: it explains update vs. create, hint behavior, supersession, and recovery from supersede failure. An agent has enough to invoke it correctly and interpret the outcomes.

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 every parameter including supersedes and project is already documented in the schema. The description largely restates those same semantics (supersedes, project=global) rather than adding new syntax or format guidance, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create or update a durable memory') and immediately characterizes the artifact ('the compact knowledge a future session must not miss'). It explicitly distinguishes itself from the sibling notes_create, so an agent can route without opening 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 explicit routing ('Long-form write-ups belong in notes_create; put the one-line lesson here') and a concrete condition for the alternative path ('Pass supersedes to replace a DIFFERENT, now-outdated memory'). When-to-use and when-to-use-something-else are both present.

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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description is consistent and adds the additive-only guarantee ('Appending only ever adds'), which tells the agent nothing existing is lost. It doesn't restate idempotency or explain the mutation's full effect, but it meaningfully supplements the safety profile.

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-loads the verb and mechanism, then routes to alternatives. Three dense sentences all carry information, though the middle sentence's framing is slightly elaborate for the payload being described.

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?

Covers purpose, id sourcing, alternatives, and additive semantics for a mutation tool with clear annotations and no output schema. The only minor gap is that it never indicates what a successful append returns, but with annotations covering safety and a full-coverage schema this is a small 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: it explains that the id is a ULID sourced from notes_create, briefings, or plan compositions, and that notes_read resolves one from a slug. This is operational guidance the schema does not provide.

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 precise verb (append), resource (an existing note's body), the key behavior (UTC-timestamped line) and the addressing key (by id). It explicitly distinguishes itself from notes_update and notes_create, so an agent can separate it from siblings without reading any 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 both when-to-use ('when a note is already the right home ... a running investigation log, a decision record') and when-not-to-use ('use notes_update to correct or restructure ... notes_create when the finding deserves an artifact of its own'). Alternatives are named with the selecting condition.

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 write/safe/non-idempotent profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds behavior the annotations do not carry: notes are auto-tagged created-by:agent, and passing plan=<slug> enrolls the note into that plan's composition. It does not describe the return value or whether the created note's identifier is needed for later notes_append calls.

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 first sentence front-loads purpose, followed by sibling routing, plan usage, and exclusions in a logical order with no filler. It is dense and slightly overpacked in a single paragraph, but every sentence carries a distinct instruction.

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 an 8-parameter create tool with full schema coverage, no nested objects, and no output schema, the description covers purpose, routing, and the plan-composition side effect adequately. The only gap is what the call returns (e.g., a note handle/ULID a follow-up notes_append would need), which matters for the chained workflow the description itself encourages.

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 every parameter including plan, project, and session is already documented in the schema, which sets the baseline at 3. The description's plan=<slug> guidance largely restates the schema's own plan description ('tags this note into that plan's composition'), adding intent framing but no new syntax or constraints.

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 a work note') and then enumerates the kinds of artifacts it produces (research finding, decision record, meeting summary), which lets an agent classify the intended payload immediately. It also explicitly contrasts itself with memory_write and notes_append, so it is distinguishable from siblings without opening their schemas.

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 routing rules: put the long-form write-up here, the one-line durable lesson in memory_write, and extend an existing note with notes_append instead of duplicating it. It also adds a clear negative condition ('Do not use this for what the repo, AGENTS.md/CLAUDE.md, or the current conversation already records'), which is rare and valuable in exclusion 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 destructiveHint=true and idempotentHint=true, but the description goes well beyond them by stating exactly what is destroyed (file + index row), that no pointer survives, and that the operation is permanent. The plan:<slug> warning about a note being another agent's inherited narrative is behavioral context no annotation 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 action and its consequence before any caveats, and each sentence is load-bearing (mechanics, when-to-use, alternatives, plan caveat). It is on the denser side at four sentences, but none are 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 destructive two-parameter tool with no output schema, the description supplies the destruction semantics, permanence, sibling routing, and the special-case caution an agent needs before calling. Nothing material 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 100%, so both the id (ULID) and the session parameter are already fully documented in the schema. The description says 'by id' but adds no format, validation, or session-scoping detail beyond the schema, so the baseline 3 applies.

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

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

Opens with a precise verb+resource ('Delete a note by id') and immediately specifies the mechanism: the markdown file leaves the disk and the index row goes with it. It explicitly differentiates itself from notes_update and notes_append, so an agent can pick it without opening sibling schemas.

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 when-to-use ('reserve it for notes that should never have existed -- a duplicate, a write into the wrong project, an agent's own scratch') and named alternatives with their conditions (notes_update to fix content, notes_append to add). It adds a further qualifier for plan-tagged notes plus a prerequisite read step, leaving nothing 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?

Adds substantial context beyond the annotations: it discloses all-or-nothing atomicity ('all edits apply together or none do, so a failed match changes nothing'), the exact-and-unique matching requirement, and the return payload ('unified diff of what landed plus the new content_hash'). With readOnlyHint=false and destructiveHint=true already declared, the description still meaningfully extends the safety and behavior picture.

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

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

Purpose is front-loaded in the first clause, followed by the matching constraint, atomicity, sibling differentiation, and return value. No sentence is filler and each clause earns its place, despite the density.

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 mutation tool with no output schema, the description covers atomicity, preconditions (exact unique match), the return format (diff + content_hash), and how it relates to sibling tools. Nothing an agent needs to invoke 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 100%, so id, edits, old_string, new_string, replace_all, session and expect_hash are all already documented in the schema. The description restates the old_string/replace_all relationship and the all-or-nothing rule, which the schema also covers, so it adds little beyond the structured fields. Baseline 3 is appropriate when the schema carries the load.

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 ('Edit an existing note in place with exact search/replace, by id') and immediately distinguishes itself from notes_update. It also names the mechanism (search/replace) and the sibling it is not, so an agent can route without opening any 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 names the alternatives and their conditions: 'notes_append only ever adds, and notes_update replaces the whole body,' and positions itself as the tool 'for correcting or restructuring part of a long note.' The when-to-use case is unambiguous and no inference is required.

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 (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavior beyond them: the fallback chain from project-scoped slug to a global note of the same slug, and the caveat that a plan's slug is not a note's. Return shape is not described, but for a read it is largely self-evident.

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, lookup modes front-loaded, no padding. The trailing sentence about plan slugs is densely compressed and reads ambiguously on first pass, which costs a point against perfect concision.

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 read-only lookup with full schema coverage, no output schema, and annotations carrying the safety profile, the description supplies the non-obvious resolution behavior (project-to-global fallback) that an agent needs in order to interpret a miss 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 baseline is 3, but the description adds meaning the schema does not: the ordering semantics of the slug lookup (current project first, then global fallback), which is the parameter behavior most likely to surprise a caller.

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+resource ('Read a note') and two lookup modes (by id, by slug within project with global fallback). Clear and distinguishable from write-oriented siblings like notes_append or notes_create, though it never names a sibling to contrast against.

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?

Conveys the resolution order (project slug, then global fallback) and warns about the plan-slug vs note-slug mismatch, which is useful context for when a lookup will miss. It does not say when to prefer this tool over recall, memory_read, or project-scoped alternatives, so guidance is implied rather than explicit.

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 declare the destructive/idempotent profile, and the description adds substantially beyond that: omitted fields are untouched, slug and id stay stable, body replace is whole-body (not a merge), tags replace vs add/remove have different blast radii, and expect_hash can refuse the write rather than overwrite another agent's edit. This is exactly the behavioral context the structured fields do not convey.

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 purpose, then layered concurrency and tag semantics in descending priority, using semicolons to keep it as one dense paragraph. It is long, but nearly every clause carries load-bearing behavior; only the repeated tag-flavor explanation borders on redundancy.

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

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

For a 10-parameter mutation tool with no output schema, it covers mutation scope, concurrency safety, and tag semantics thoroughly. The remaining gap is not addressing notes_edit, so an agent choosing between two very similar updaters is left without disambiguation.

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; the description still adds value by explaining the ORDER of application (add/remove after tags) and the 'prefer add/remove' rule that the schema states more neutrally. It doesn't add much to id/title/project/description beyond what the schema already documents.

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 ('Update a note's fields by id') and enumerates the mutable fields, so the agent knows exactly what is being mutated. It differentiates from notes_append explicitly. However it never distinguishes itself from the near-identically named sibling notes_edit, which is the most likely confusion point.

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 alternative routing: use notes_append when you only mean to add to the body, and prefer tags_add/tags_remove over a full replace. It also states when to supply expect_hash (to avoid clobbering a concurrent edit) and that tags_remove is the only way to clear a tag. These are concrete when-to-use conditions, not 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 only declare the safety profile (non-read-only, non-destructive, idempotent, closed-world); the description adds the semantics that matter: existing slug is an error rather than an update, this tool never renames or edits, "global"/"all" are reserved, slug defaults to a slugified name, and isolation can only be set at creation because changing it later detaches family and parent links.

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?

Five dense sentences that are front-loaded with purpose and the "you rarely need this" caveat before the caveats and constraints. Slightly long, and a few clauses (auto-registered projects are named after their slug) could be tightened, but nearly every sentence carries routing or constraint 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 5-parameter mutation tool with no output schema and no annotations covering behavior, the description covers when to use it, duplicate-slug failure, reserved slugs, and irreversible isolation. The only gap is that it never hints at what a successful call yields (e.g., the created project/slug), which is minor given the deliberate omission of return-value detail.

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 3 baseline applies, but the description still adds value the schema lacks: the slug default rule (slugified name), the reserved slug values, and the error-not-update behavior for existing slugs. Isolation and session semantics largely restate the already-detailed schema text, hence not a 5.

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 ("Register a project up front") and immediately scopes it against the many siblings that auto-register projects (memory_write, notes_create, tasks_add, capture_url, trial_record). An agent can tell project_create apart from those 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 states when NOT to use the tool ("You rarely need this"), enumerates the alternative paths that already register projects, gives the only two legitimate use cases (naming before writes, creating unused projects), prescribes a prerequisite (call project_list first, citing duplicate slugs as the failure mode), and routes the split case to gardener_split.

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 cover the read-only/idempotent safety profile, and the description adds genuinely new behavioral context: the open|confidential|sealed isolation states, the rule that confidential/sealed projects are readable only from a bound session, and that sealed takes no external writes. It also clarifies it returns identity, not contents.

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

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

Purpose and returned fields are front-loaded, and each sentence carries information. The middle sentence is a long, em-dash-heavy clause ('the failure this prevents', 'writing outside that on purpose') that could be tightened, keeping it just short of maximum.

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 still tells the agent what each row contains and what the isolation values mean. Combined with annotations covering the safety profile and a fully documented schema, an agent has everything needed to call this 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?

There is one optional parameter and schema description coverage is 100%, so the schema already fully documents the session argument. The description discusses session binding inheritance conceptually but adds no syntax or format detail for the parameter itself, so 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?

Opens with a specific verb and resource ('List every project') and enumerates the returned fields (slug, name, description, isolation). It explicitly distinguishes itself from sibling tools: project_create is named as a consumer of this data, and recall is named as the tool for contents rather than identity.

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 when-to-use (learn the exact slug before a deliberate cross-project write or project_create) and an explicit when-NOT-to-use ('You usually do NOT need it to pick a scope'), explaining that memory/note/task calls inherit the project from the session binding. It also routes to the correct alternative for content search (recall).

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 a safe, idempotent, non-destructive read. The description adds real context beyond that: scope is the current project plus global items, work-record hits carry a status and match on keyword only, and kind-without-query flips to a newest-first browse mode.

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

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

Three sentences, front-loaded with the core purpose and scope before the special cases. Dense but every clause carries information; the parenthetical asides add slight clutter but no wasted sentences.

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 notes that work-record hits carry a status. Combined with full schema coverage and read-only annotations, an agent has enough to call it correctly, though return shape and ranking behavior are only lightly touched.

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 the parameters are already well documented (including the kind/scope interaction and session semantics). The description largely restates the browse behavior and scoping that the schema already covers, 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 (search) and enumerates the resources covered (memories, notes, tasks, trials, session findings) via fused semantic+keyword matching. Explicitly positions itself as 'the single search entry point', which distinguishes it from siblings like memory_read, notes_read, and tasks_list.

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?

Declares itself the single search entry point, implicitly routing the agent away from the read/list siblings, and describes the browse alternative (kind set with no query). It does not explicitly say when to prefer memory_read/notes_read/tasks_list instead, so it falls short of a full when/when-not statement.

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, idempotent mutation (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds that findings are persisted for future briefings, which is useful context, but says nothing about what happens to the session afterwards or the effect of re-running.

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 with the primary action and effect front-loaded and the fallback session behavior second. Nothing 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 mutation tool with no output schema, the description conveys the core outcome and the session-resolution default, and the rich schema handles parameter detail. Minor gaps remain around post-completion session state, but nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters in depth, including the session/session_id precedence. The description's 'Uses the bound session unless you pass one' only restates what the schema already states, adding little beyond the baseline.

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 (complete) and resource (session) plus the effect (persisting findings for future briefings), which sets it apart from the mutating sibling session_update. The distinction from session_update is implied rather than explicit, so it falls short of 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?

The closing sentence ('Uses the bound session unless you pass one') gives default-behavior context, but there is no explicit when-to-use guidance versus session_update or session_start. Usage is only 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 declare the safety profile (mutation, idempotent, non-destructive), so the burden is lighter. The description adds genuinely non-annotation behavioral context: the call returns a briefing, and 'later calls inherit the session's project, so they need no project argument' — a stateful, connection-scoped side effect an agent must know.

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, each front-loading purpose before conditions. The first sentence leads with the core action; the exception and usage clauses follow. No filler sentences, though it is on the longer side for the amount of new 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?

No output schema exists, so the mention that the call returns 'its project briefing' usefully fills that gap. For an 8-parameter, non-destructive mutation tool with annotations and full schema coverage, the description covers purpose, usage conditions, and stateful behavior — minor gaps only.

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 the schema already documents all 8 parameters in detail. The description only loosely gestures at parameter meaning ('resume a named session', 'move this connection to another project') and adds no syntax or format not already in 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?

States a specific verb and resource: 'Bind this connection to a work session and return its project briefing.' It also clarifies the automatic-hook case that does not need this call. It stops short of explicitly differentiating from sibling tools like session_update or session_end, 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?

Gives explicit when-to-use conditions ('bind a client without hooks, to move this connection to another project, or to resume a named session') and an explicit when-NOT-needed case ('Claude Code and Codex agents running the Seamless hooks ... do not need this'). Nothing about invocation timing is left 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 this a non-destructive, idempotent write, and the description adds the useful behavioral fact that a session is bound by default. It does not disclose the key remaining trait for a write tool: whether passing new findings replaces or appends to previously recorded interim findings, which matters given idempotentHint=true.

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 with zero filler; the core action is front-loaded and the parameter default is stated immediately after. Nothing here could be cut 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 three-parameter write tool with no output schema, the description covers purpose and session binding adequately and the schema carries the parameter detail. The one real gap is the overwrite-vs-append semantics of repeated updates, which an agent needs in order to call this correctly over a session's lifetime.

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 the schema already documents session, findings, and session_id including the precedence of session_id. The description's 'uses the bound session unless you pass one' restates the schema default rather than adding syntax or edge-case detail, so baseline 3 is appropriate.

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

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

States a specific verb ('Record') and resource ('interim progress on the current session') with a parenthetical clarifying what is stored ('working findings so far'). It is distinguishable from session_start/session_end, but does not say how it differs from other note-recording siblings like memory_write, memory_append, or notes_append.

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 gives real guidance on the session parameter ('Uses the bound session unless you pass one'), which implies the common case. However, there is no explicit statement of when to use this tool versus memory_write/notes_append or session_start/session_end, so usage is only loosely 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 declare non-readOnly, non-idempotent, non-destructive, so the mutation profile is covered structurally; the description adds real behavioral context beyond that: depends_on ids must exist and must not create a cycle, and 'done or dropped' both unblock dependents. It does not mention duplicate-create behavior, which is the main residual gap given idempotentHint=false.

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

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

Three sentences, front-loaded with the core action, then the dependency contract, then the readiness rule. No filler or restatement of the name.

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 create tool with no output schema and rich per-parameter schema docs, the description covers the essential semantics. The one omission is what the call returns (e.g., the new task id), which matters because depends_on requires ids of existing tasks.

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; the description then adds meaning the schema lacks, notably that blockers are unblocked by 'done or dropped' states and that a task is ready only with no open/in_progress blocker. This clarifies depends_on semantics beyond the schema's simpler 'task ids this task is blocked by'.

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 ('Add a task') plus the distinguishing destination ('dependency-aware ready queue'), which separates it from siblings like tasks_update, tasks_claim and tasks_ready. An agent can identify the tool's role 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?

Usage context is implied by the explanation of depends_on and the definition of 'ready', which tells the agent when a task becomes actionable. However, it never names an alternative or a when-not condition (e.g., use tasks_update to modify an existing task, tasks_claim to take one), so routing guidance is left 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing atomicity, lease lifecycle (refresh on re-claim, expiry makes a task reclaimable), the literal refusal messages, and the release paths. That is exactly the behavioral context an agent needs to act on a failed claim.

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 and effect, and every sentence carries information. It is somewhat dense with nested parentheticals in the refusal-cause clause, which costs a little readability without wasting words.

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

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

No output schema exists, so the description carries the return-side burden and does so: it names the success effect, every failure mode with its literal message, and the release/heartbeat cycles. Nothing an agent needs in order to call this correctly or interpret a refusal 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; the description adds meaning by explaining how the lease behaves over time (heartbeat on re-claim, lapse then reclaim) and how releasing works, which contextualizes the lease_seconds and session parameters. It stops short of adding format or precedence detail for id/session beyond the schema text.

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 precise verb+resource+state transition: 'Atomically claim a task for the current session, moving it to in_progress with a lease.' An agent can distinguish this from tasks_release, tasks_update, and tasks_ready without opening any 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 enumerates exactly when the call is refused and why ('task already claimed', 'task blocked', 'task closed'), tells the agent what to do about blockers ('finish those first'), and routes to the alternatives: tasks_release or tasks_update done/dropped for release, session_end for bulk release.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real behavioral context: the default plan-step exclusion, the newest-first ordering, and the notable fact that an id lookup ignores project/status/plan and needs no session scope — a non-obvious escape hatch an agent could not derive from the 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?

Three tight sentences, zero filler, and the primary behavior (list tasks, filtered, newest first) is front-loaded before the two alternate modes. Every clause carries information an agent needs to choose the right mode.

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 read-only list tool with no output schema and five zero-required parameters, the description covers the defaults, both alternate modes, the response shape for the id path, and the session/crediting implication. Nothing needed to invoke it correctly is absent.

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 the schema already documents all five parameters and a baseline of 3 would be defensible. The description adds genuine framing on top: the mode-selection semantics of plan= vs. default vs. id=, and that the id path bypasses session scoping and returns a single-element tasks array.

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 (list a project's tasks) plus the ordering (newest first) and two alternate modes (plan-step listing, single-task lookup by id). It is immediately clear what the tool returns. It does not, however, name or contrast itself with the adjacent siblings (tasks_ready, tasks_claim), so an agent must infer the boundary between browsing and claiming work.

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 gives explicit conditional guidance: default excludes plan-step tasks, use plan=<slug> to see a plan's steps instead, use id=<task id> for a direct single-task lookup. What is missing is the 'when not to use this' side — nothing says to prefer tasks_ready for actionable work or tasks_claim to take a task.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds non-obvious behavior beyond that: results are ordered oldest first, and blocked tasks are included alongside their still-open blockers.

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 primary behavior, then the default/override rule. Every clause carries information; nothing is 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 read-only list tool with no output schema, the description adequately conveys what the return set contains and how it is ordered. It omits anything about result limits or pagination, a minor gap given the tool's simplicity.

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 all three parameters are already documented with defaults and scoping semantics. The description restates the plan parameter's effect but adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

Names a specific verb+resource ('List the actionable (ready) tasks for a project') and defines the exact selection criteria (open tasks with no unfinished blocker) plus what else is returned (blocked tasks with their blockers). This distinguishes it from siblings like tasks_list, tasks_claim, and tasks_release.

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?

Explains the default behavior and the escape hatch: plan-step tasks are excluded by default, and passing plan=<slug> switches to that plan's steps. It does not name sibling alternatives such as tasks_list for a fuller view, so it stops short of explicit 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 the mutation safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description still adds real value: the exact post-state (status=open, claim cleared), the authorization requirement (holder only), and the downstream effect that another agent can then claim it. It does not say what happens on a failed release or on session end.

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 its effect, then the constraint. No filler and nothing redundant with the name or 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?

For a mutation tool with no output schema, it covers the essential semantics: what changes, who may call it, and the benefit to other agents. Minor gaps remain around failure/error behavior and whether releasing happens implicitly at session end.

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

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

Schema description coverage is 100% and the session/session_id params are thoroughly documented in the schema itself. The description only implies session scoping via 'the current session holds' and adds no syntax or precedence detail beyond the schema, so the baseline 3 is correct.

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 (release) and resource (task) and spells out the resulting state transition: 'status back to open, claim cleared'. The phrase 'so another agent can claim it' makes the inverse relationship to tasks_claim unambiguous without opening 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?

The precondition 'Only the current holder may release' tells the agent when this tool is valid, and 'a task the current session holds' scopes the use case. It stops short of naming an alternative (e.g. tasks_update for status changes) or stating when-not to use 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: status transitions to done/dropped close the task and unblock dependents, and locked tasks fail with an error. This gives the agent a clear understanding of side effects and constraints.

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 only: the first states the main capabilities, the second covers the critical lock behavior. No fluff, front-loaded, and every sentence adds essential 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 tool with 8 parameters and no output schema, the description covers the primary update types and the locking mechanism. It does not explain the return value or all edge cases (e.g., adding dependencies to a closed task), but the information provided is sufficient for typical usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the status enum values, the comma-separated string acceptance for add_depends_on, and the condition for using the session parameter. It does not elaborate on every parameter (e.g., project, session_id precedence) but provides sufficient context beyond the schema.

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

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

The description clearly states 'Update a task' and enumerates specific fields (status, title, body, dependencies). It distinguishes from siblings like tasks_add and tasks_claim by focusing on updates and mentioning lock behavior unique to this tool.

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 explains when to use the tool (to update task fields) and notes that attempting to update a locked task fails. It provides guidance on when the session parameter is needed. However, it does not explicitly mention alternatives (e.g., using tasks_release to unlock) or when not to use this tool.

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 annotations (which already declare readOnly/idempotent/non-destructive), the description discloses genuinely non-obvious behavior: counts are machine-wide and identical for every caller, while only topInjected/topUtility are fenced by project isolation, so those lists can legitimately come back shorter than the counts imply. That is exactly the kind of discrepancy an agent would otherwise misread as a bug.

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

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

Three sentences, front-loaded with the payload contents before the fencing caveat. The middle sentence is dense but every clause (machine-wide, fenced lists, shorter-than-implied) carries distinct meaning; the trailing "Read-only." is the only mild redundancy given readOnlyHint.

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 must convey what comes back and it largely does, naming the count groups, the top-injected/topUtility lists, and the events-by-kind breakdown. It stops short of describing the response's shape or ordering, but for a read-only roll-up it 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 description coverage is 100% and the single session parameter is documented in detail there (formats, defaulting, stateless-connection guidance). The description adds nothing about the parameter, so the baseline of 3 for schema-does-the-work 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 names a specific verb-plus-resource ("Report a roll-up of activity") and then enumerates exactly what is rolled up: memory/note/session/task counts, retrieval totals, pending gardener proposals, and events by kind. That enumeration makes it trivially distinguishable from siblings like recall, tasks_list, or gardener_proposals, which each cover only one slice of this report.

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 rather than stated: an agent can infer this is the overview/dashboard call you make instead of stitching together recall + tasks_list + gardener_proposals. But there is no explicit 'use this when…' or 'use X instead when you need per-item detail' routing, and no prerequisites are given beyond the session parameter's own schema text.

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