Wenlan

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds genuinely new context: a mandatory human-confirmation gate, a transport availability caveat, and the cross_space_discovery space requirement. It does not explain what the destructive effect actually is (what merging or removal occurs), which is the remaining gap given a destructive mutation.

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

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

Three short sentences, front-loaded with the action and its precondition, then the conditional parameter case, then the environment limitation. No sentence is redundant.

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

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

For a two-parameter destructive mutation with full schema coverage and no output schema, the description covers the prerequisite human decision, the conditional parameter, and transport limits. Only the concrete effect of acceptance (what is changed or removed, given destructiveHint) 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 coverage is 100%, so both parameters are already documented, including the space parameter's purpose and default null. The description's note about passing the destination space for cross_space_discovery largely restates the schema, adding only the card-type trigger condition, 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 plus resource with scope: 'Accept one listed refinement proposal by id.' The words 'one listed' and 'by id' distinguish it from reject_refinement and list_refinements in the sibling set, and the user-decision gate further narrows the action.

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

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

Gives a concrete precondition (an unambiguous item-level accept decision from the user) and a conditional usage rule for cross_space_discovery, plus an explicit environment restriction (local stdio only, not remote HTTP). It does not name the alternative tool (reject_refinement) for the negative case, so it falls short of a full when/when-not/alternatives treatment.

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 destructiveHint annotation: it says exactly what is destroyed (the target memory's content is replaced by the proposed revision), what is removed (the revision row from the pending list), what is returned (the consumed revision id), and what error condition to expect. The transport limitation is a behavioral fact annotations could never express.

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 short sentences, no filler: effect first, return value next, error condition next, environment constraint last. Each sentence carries a distinct, actionable fact.

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 one-parameter destructive mutation with no output schema, everything needed is present: the mutation effect, the return value, the error case, and a transport restriction that would otherwise cause a runtime surprise.

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 a single required parameter at 100% schema coverage, the schema already defines target_source_id fully. The description's 'target memory' phrasing reinforces the intent but adds no format or edge-case detail about the identifier itself, so the baseline 3 applies.

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

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

States a specific verb and resource ('Accept a pending memory revision') and immediately disambiguates from siblings by describing the state change against the target memory rather than a revision row. An agent can distinguish this from dismiss_revision and accept_refinement 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 the precondition implicitly (a pending revision must exist for that target) and names the failure mode if it doesn't, plus a hard availability constraint ('local stdio only'). It never explicitly routes to dismiss_revision for the reject path, so it falls short of a full when/when-not/alternatives 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 readOnlyHint=true and destructiveHint=false; the description adds real value beyond them by clarifying that reading never creates or mutates a Brief and that creation happens through a handoff update instead. It does not describe output shape or size of the Brief.

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

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

Three sentences, front-loaded with purpose then usage then the read-only guarantee; every sentence carries distinct information and none 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?

For a zero-required-param read tool with annotations covering safety and full schema coverage, the description supplies the missing usage and mutation semantics. The main gap is what the returned Brief actually contains, which is left entirely implicit.

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 restates the omit/provide `topic` behavior nearly verbatim from the schema and adds nothing about `space` or `session` beyond what is already documented.

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

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

States a specific verb and resource: 'Read the current Space Brief,' with the scope (Space) and mode (topic append) named. It implicitly separates itself from update_brief by asserting reads never create or mutate, but it does not name or contrast a sibling explicitly.

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

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

Gives clear trigger conditions — resuming project work or when the user asks to catch up — plus an explicit rule for when to omit vs. supply `topic`. No alternatives are named (e.g., update_brief, capture), so there is no 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 flag a non-idempotent, destructive write; the description goes well beyond that by explaining that `supersedes` replaces an existing memory in retrieval, that such corrections can be staged with `gated: true` when trust is below full, and what to tell the user. It also discloses backend auto-classification and the `enrichment: paused/off` state that changes behavior, which annotations alone cannot 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 purpose then policy, organized under clear ALL-CAPS headers that make it scannable. It is nonetheless long, and a few lines restate each other ('Atomic: one idea per memory. Each call is one atomic idea'), which costs it the top score.

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 nine-parameter mutation tool with no output schema, the description covers the decisions an agent actually has to make: whether to store, what quality bar to hit, when to set memory_type, when to use supersedes and what the gated response means. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real decision guidance beyond the schema: default to omitting memory_type and why over-specification fails, the 'decision' exception with its alternatives-weighed criterion, and the no-model case where memory_type must be set. Confidence, space, and entity are left to the schema, so it stops short of 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?

Opens with a specific verb and resource plus a scope qualifier: 'Capture a memory: one durable insight the user's wiki should keep.' That immediately separates it from recall, forget, write_page and confirm_memory without needing the schema.

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

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

Explicit when-to-store triggers (preference, decision, correction, durable fact) framed as 'a floor, not a trigger', a dedicated WHEN NOT TO STORE list with concrete exclusions, and an explicit alternative ('recall first if unsure'). This is about as complete a routing policy as a tool description can carry.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still adds real behavioral context: the operation only applies to memories in a pending state, and the negative counterpart is forget. It doesn't say what confirmation does downstream (e.g., whether the memory becomes recallable) or how it errors on a non-pending id.

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

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

Three short sentences: action first, then usage context, then the reject alternative last. No repetition of annotation data and no filler.

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

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

For a one-parameter tool with annotations present and no output schema, the description covers the action, the input source, and the sibling routing an agent needs. Only the post-confirmation effect and failure mode for already-confirmed or unknown ids are left implicit.

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

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

Schema coverage is 100% and the single parameter is fully documented, including where to source the value, so the baseline of 3 applies. The description's 'by source_id' phrasing loosely reconciles the memory_id field name with the source id concept, but that mapping is already stated in the schema itself, so it adds little beyond it.

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 (confirm a pending memory) plus the required identifier, and explicitly contrasts itself with the reject path (forget). An agent can distinguish it from list_pending, forget, and recall without inspecting 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 the operating context ('during review to accept a memory the agent captured'), the origin of the input ('typically picks from a list_pending result'), and the explicit alternative ('To reject instead, call forget with the same memory_id'). When-to-use and when-to-use-something-else are both spelled out.

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 idempotentHint=true and destructiveHint=false, so the description's idempotency claim adds little. What it does add is real behavioral context: entity extraction is normally handled by daemon enrichment, and when enrichment is disabled capture's `entity` links only pre-existing entities, which is why the entity must be created first. Permission/scope limits and return shape are not covered.

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

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

Purpose is front-loaded in sentence one, followed by usage rules and the enrichment caveat in a logical order. The middle clauses are dense and long-winded, but every sentence carries decision-relevant information rather than repetition.

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

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

No output schema exists, but the description implies a resolved id is produced ("resolved ids are needed for a relation"). It covers the critical precondition — enrichment configuration — that determines whether this tool is needed at all. A brief note on what comes back (canonical id, whether a new entity was created) would close the remaining gap.

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

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

Schema description coverage is 100%, so name, space, confidence, and entity_type are all documented with examples and defaults in the schema. The description adds no parameter-level meaning beyond what is already there, 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+resource: "Resolve a durable named entity idempotently." It separates itself from the nearest confusable sibling (capture) by explaining that capture handles ordinary captures and enrichment extracts entities. The create/resolve duality in name vs. description is reconciled by the idempotency clause, though the phrasing is slightly abstract.

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-call (user establishes a durable named entity, or resolved ids are needed for a user-stated relation), explicit when-not-to-call ("Do not call create_entity for every ordinary capture"), and a concrete fallback condition tied to whether enrichment is paused or off. An agent can decide without further 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 destructiveHint=true and idempotentHint=false; the description earns its keep by explaining why – conflicting relations may be auto-superseded by the daemon. It also discloses the provenance requirement (a backing source_memory_id) and that names are not auto-created. It stops short of saying whether superseding is reversible or what the response contains, so not a 5.

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

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

The gating rule is front-loaded in the first sentence, followed by the workflow in execution order. It is dense but nearly every clause carries a distinct constraint; only the endpoint-id sourcing is stated twice (once in prose, once in 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?

No output schema exists, yet the description supplies the preconditions, the prerequisite tool chain, the supersede side effect, and the source-provenance rule an agent needs before invoking a destructive write. 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 coverage is 100%, so a 3 is the baseline; the description adds genuine semantics on top by specifying where each id must come from (create_entity for endpoints, capture for source_memory_id) and by defining relation_type as a snake_case present-tense verb.

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 source-backed directed relation') plus the gating condition ('only when the user explicitly states a durable relation'). It is clearly separable from create_entity, which it explicitly references as a prerequisite step rather than a substitute.

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 ordered workflow (resolve ids with create_entity, capture the statement, then pass the ids plus source_memory_id) and an explicit negative rule: 'Entity names are not accepted or auto-created. Never infer an unstated relation.' Both when-to-use and when-not-to-use are covered.

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

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

Annotations already flag destructiveHint=true, but the description goes beyond them by disclosing exactly what is destroyed ('both the DB row and the on-disk md projection') and what recovery looks like ('Pages without sources can be re-derived by running /distill again'). That is real behavioral context, not a restatement of structured hints.

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 with zero waste: the action and its guard clause come first, the destruction scope second, the alternative third. No sentence repeats the title or annotations.

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 single-parameter destructive tool with no output schema, the definition covers the safety profile, the physical scope of deletion, the recovery path, and the correct sibling alternative. An agent has everything needed to decide whether and how to call it.

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 parameter, page_id, and the schema already documents it fully at 100% coverage, including the legacy 'concept_abc' format and where to obtain it from distill output. The description adds only the 'by id' framing, so the schema is doing the heavy lifting and 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 and resource ('delete a page by id') and immediately distinguishes the operation from the sibling write_page by explaining that write_page refreshes while preserving page_id and history. An agent can tell the two apart 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 an explicit precondition ('only when the user explicitly asks to remove it') and names the alternative action ('to refresh an existing page, use write_page'). It even covers the edge case of re-deriving source-less pages via /distill, 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?

Annotations already flag destructiveHint=true, and the description goes meaningfully beyond them by scoping the destruction ('deletes the revision row; the original memory is unchanged'), stating the failure mode when the precondition is unmet, and disclosing a transport restriction. These are exactly the behavioral facts an agent needs and are not derivable from the structured fields.

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 short sentences, front-loaded with the action and effect, followed by the error condition and the transport caveat. No sentence is filler; each carries a distinct operational fact.

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 one required string parameter, no nested objects, and no output schema, the description covers effect, precondition, failure mode, and availability. It does not say where target_source_id values come from (e.g., list_pending_revisions), the one small gap preventing a 5.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema itself. The description only refers to 'that target' without adding format, sourcing, or identifier-resolution detail, 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?

States a specific verb ('Dismiss') and resource ('pending memory revision'), and immediately clarifies the exact effect ('Deletes the revision row; the original memory is unchanged'), which cleanly separates it from accept_revision and forget. An agent can pick this over sibling revision tools 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?

Implies the precondition clearly ('pending memory revision ... for that target') and adds an explicit error condition when no pending revision exists, plus a transport-level exclusion (local stdio only). It does not name the complementary siblings (accept_revision, reject_refinement) that an agent would weigh against this one, so it falls short of a 5.

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

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

The description goes beyond the annotations by explaining that force=true clears the user-edited guard and can replace page prose, and that rebuild may send page and source material to an external LLM provider. These are important side effects that complement the destructiveHint and openWorldHint annotations rather than contradicting them.

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

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

The description is front-loaded with the core action and then organizes target behavior, force semantics, external LLM implications, and usage guidance. It is somewhat dense and repeats a few schema points, but the structure is clear and every section is useful.

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 complex, side-effecting operation with no output schema, the description covers invocation modes, force implications, external LLM exposure, background behavior, and when to call it. Nothing essential for selecting or invoking the tool 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?

The schema already documents both parameters at 100% coverage, so the baseline is 3. The description reinforces the target scopes and force behavior, but much of that information is already present in the schema descriptions.

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 action, 'Trigger Wenlan's distillation pass,' and clearly distinguishes the no-target full pass from targeted re-distillation. It specifies the accepted target forms (page id, entity name, space), making the tool's scope and resource precise.

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 explicitly says to use the tool when the user asks to synthesize, distill, or rebuild a page, and it warns against redundant triggering when the daemon already distills in the background. This gives both the triggering condition and the condition under which not to call it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: irreversibility, the history-preserving supersedes alternative, and the conditional staging-for-review behavior tied to trust level. It does not describe what the tool returns or confirms, which keeps it from a 5.

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

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

Front-loaded with the core action and trigger phrases, then escalates to prerequisites and the safer alternative. The trust-level staging sentence is long but carries non-obvious information, so it earns its place; overall slightly denser than needed.

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 one-parameter destructive tool with no output schema, the description covers purpose, prerequisite, irreversibility, alternative, and conditional staging. What it omits is only marginal: whether a success confirmation or error is returned and how to recover after deletion.

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

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

Schema coverage is 100% and the single parameter already documents 'source_id of the memory to delete... from recall results,' so the description largely restates it; the added workflow hint (fetch via recall first) is useful but mirrored in the schema. Baseline 3 applies when the schema does the heavy lifting; note the minor terminology drift between 'source_id' in prose and 'memory_id' in the schema.

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

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

The first sentence gives a specific verb and resource ('Delete a memory by ID'), and the trigger phrases ('forget this', 'delete that') disambiguate it from siblings like recall or capture. An agent can distinguish this from write_page/delete_page or supersedes-based correction paths 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 exactly when to use it (user asks to forget/remove something), states the prerequisite ('get it from recall first'), and explicitly names the preferred alternative for corrections: storing a new memory with supersedes. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the result is a chain, ordered by depth with 0 as current, and it names the motivating scenario (verifying a recorded correction). It stops short of saying what happens for a memory with no revisions or how deep chains can get.

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 what, then the when. No filler and every clause carries information an agent would otherwise have to infer.

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 one-parameter read tool with rich annotations and no output schema, the description covers purpose, trigger conditions, and return ordering. A brief note on the response shape (e.g., fields per revision, behavior when no prior versions exist) would close the remaining gap.

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

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

Schema coverage is 100% and the single parameter's schema description already states the id formats ('mem_abc', 'merged_<uuid>') and the depth ordering. The description only restates the ordering, adding no syntax or format detail beyond structured data, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch the supersede chain for one memory') plus the ordering semantics (depth 0 = current). This is clearly distinguishable from the sibling 'recall' tool and from 'get_page_revisions' by resource type.

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 gates usage: 'Use after recall only when the user explicitly asks for that memory's history or evolution, or to verify that a correction was recorded.' It names the prerequisite tool (recall) and the two narrow conditions that justify the call, which is exactly the routing guidance an agent needs.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world behavior, so safety is covered. The description adds the newest-first ordering and hints at entry content (source memories that triggered a re-distill), but says nothing about result volume or pagination behavior.

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

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

Two sentences, no waste, with the core purpose and ordering front-loaded before the usage constraint. Every clause carries information an agent can act on.

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 single-parameter read tool with rich annotations and no output schema, this covers purpose, ordering, and usage gating adequately. The only gap is how many revisions come back and whether the result is capped, which matters for a changelog tool.

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

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

Schema description coverage is 100% and the single page_id parameter is documented there, including its own restatement of the newest-first ordering. The description adds no syntax or format 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?

The description states a specific verb and resource ('Fetch the version changelog for one page') plus the ordering guarantee, so an agent knows exactly what it returns. It implies differentiation from get_memory_revisions via 'one page', but never names that sibling, so it falls short of a full 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?

'Use only when the user explicitly asks for a page's changelog, version history, or which source memories triggered a re-distill' gives a clear gating condition and enumerates the triggering phrasings. It does not name alternatives such as get_memory_revisions or page_basis, so no explicit when-not 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 readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds real value beyond them by spelling out exactly what comes back (source memory ids enriched with title, content, type, space), which matters because there is no output schema. It says nothing about result limits or ordering, which keeps it out of the top band.

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 what is fetched and what it contains, followed by the one operational fact needed to call it. No repetition of annotation or schema content.

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 single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, return shape, and id provenance. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100% and the schema already explains that page_id is opaque, non-URL, and returns distilled source memories. The description nevertheless contributes provenance the schema lacks — that the id comes from the `stale_pages` block in distill output — which is the practical question an agent has here.

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

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

It uses a specific verb and resource ("Fetch the source memories of a page") and defines the resource precisely as the memory ids the page was distilled from. The return payload is enumerated (title, content, type, space). It does not explicitly contrast with near siblings such as page_basis or read_page, 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?

It states the concrete usage context: the /distill skill calls this on the stale-page refresh path after reading the page id from the `stale_pages` block in distill output. That is genuine when-to-use guidance. No explicit exclusions or named alternatives are given, so it isn't a 5.

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, the description discloses that general returns the text `wenlan lint` prints while deep returns a canonical typed report, that incomplete takes precedence over findings, that work_digest reads only this local MCP process and ignores other parameters, and that paging follows next_offset before submitting exactly one verdict per candidate.

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 opening sentence is front-loaded, but the rest is a dense single paragraph mixing profile behavior, paging, adjudication consent, and submission protocol. Every detail is relevant, yet the lack of structural separation makes the definition harder to scan than necessary for a 7-parameter tool.

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 complex tool with no output schema, the description explains the divergent return shapes (raw text for General, typed report for Deep) and the work-packet page shape. It does not explain what 'Incomplete' means operationally or how lint findings relate to the sibling repair tools, leaving a small completeness 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 the baseline is 3, but the description adds meaningful cross-parameter behavior: profile selects the return format, work_digest changes the entire mode and causes other parameters to be ignored, offset and limit page the work packet, and agent_assist is Deep-only. It still leaves some nuance (e.g., precise interaction of space with each profile) to the schema.

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

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

The description clearly states the core action (run Wenlan's read-only system lint) and distinguishes two execution profiles plus a work-packet paging mode. It does not explicitly differentiate itself from sibling lint_repair_* tools, which is the main gap for a 5.

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

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

It gives clear mode-selection context: general is the default bounded profile, deep adds expensive checks and semantic candidates, agent_assist requires explicit consent, and work_digest switches to paging the cached packet. It never names sibling tools or tells the agent when not to use this tool, so it stops short of full alternative 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 destructive=true, readOnly=false and idempotent=true; the description adds real context beyond them — CAS canonical writer semantics, refusal of stale targets, the exact approval-string gate, and a 'local stdio only' execution constraint. It does not say what state is mutated on the target page or how to recover from a refusal, keeping it below a 5.

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

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

Three short sentences, front-loaded with the action and followed by the safety gate and environment constraint. No filler or repetition.

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

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

For a destructive, non-read-only mutation with no output schema and two undocumented parameters, the description covers the safety gate and environment but omits how to obtain the manifest id/digest, what the call returns, and what happens to the page on success. Adequate but with clear gaps an agent would hit at call time.

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 33%: only `approval` is documented, and its template is repeated in the description with little added value. `manifest_id` and `approved_manifest_digest` remain undefined — the description implies they come from a prior prepare and must match, but never states provenance or format, so the coverage gap is only partly compensated.

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 — 'Apply exactly one prepared lint repair' — plus the mechanism ('daemon's CAS canonical writer') and scope ('exactly one'). The word 'prepared' implicitly positions it downstream of lint_repair_prepare and lint_repair_verify, though no sibling is named outright.

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 concrete preconditions: an exact user approval string is required and stale targets are refused, so the agent knows a prepare step and fresh digest are needed. It does not explicitly name lint_repair_prepare/lint_repair_verify as the required adjacent calls or say when to skip 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?

Adds context beyond annotations: artifacts are private and immutable, canonical data is never mutated, lost responses may already have created artifacts, paging is byte-bounded, and the tool is local stdio only. These are meaningful mutation and retry semantics consistent with readOnlyHint=false, idempotentHint=false, and destructiveHint=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?

The description is front-loaded with purpose and then organized by mode, behavior, retry caveat, and environment constraint. Every sentence carries operational information for a complex six-parameter tool.

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 the full calling model for a complex tool: opening a plan, paging with plan_id/plan_digest/offset, preparing a choice, artifact behavior, retry risk, and local-only constraint. No output schema exists, yet the description still explains the relevant returned fields and pagination handling.

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 schema coverage at 100%, the schema already documents each parameter, but the description adds mode-level semantics: which parameter combinations open versus page versus prepare, what next_offset means, and that choice turns exactly one Review Item into an approval-gated manifest. It also describes the return shape, including source_reports and page entries, despite no output schema.

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

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

States a specific verb and resource: plan or prepare lint repairs from cached reports for the exact lint_scope, explicitly excluding pasted reports. It also distinguishes its behavior from the apply step by saying it produces approval-gated manifests and never mutates canonical data.

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

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

Gives explicit branch conditions: only lint_scope opens a new plan, plan_id plus plan_digest plus offset pages an existing plan, and choice prepares exactly one Review Item. It also warns not to retry a lost plan response and notes the extra requirement for reclassification.

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 write (readOnlyHint=false), idempotent, non-destructive, closed-world; the description adds meaningful traits beyond that: the four rejection conditions (surviving target evidence, new actionable findings, stale reports, non-target state changes) and the 'local stdio only' environment constraint. It stops short of explaining permissions or exactly what record is written.

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 with the core action front-loaded, then the rejection semantics, then the environment caveat. Dense jargon but no wasted words.

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

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

For a 6-parameter mutation tool with a nested object, no output schema, and low schema description coverage, the description covers the workflow and rejection rules but leaves the digest/receipt parameters and the verification outcome undocumented. Adequate but with clear gaps.

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

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

Schema coverage is only 33%. The description alludes to the general_report and deep_report inputs via 'General and applicable agent-assisted Deep lint', but says nothing about manifest_id, manifest_digest, apply_receipt_digest, or next_apply, leaving most parameters to bare schema types.

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

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

Names a specific verb and resource: 'Record verification for an applied lint repair', with a precondition attached (after rerunning General/Deep lint). This clearly separates it from lint_repair_prepare and lint_repair_apply, though it never names those siblings explicitly.

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

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

States the triggering condition precisely ('after rerunning complete General and applicable agent-assisted Deep lint') and lists the states that cause rejection. It gives clear context but does not explicitly name alternatives or say when not to call it versus prepare/apply.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by listing exactly which fields are returned and how filtering/pagination work, filling a gap because there is no output schema. It does not mention auth or rate limits, but that is minor given 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?

The description is front-loaded with the core purpose, followed by concrete usage examples and a one-line note on filtering/pagination. Every sentence earns its place with no filler.

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

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

For a read-only listing tool with no output schema, the description fully covers what is returned, why to use it, and how to filter/paginate. Annotations handle safety, and the schema covers all parameters, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema fully documents limit, space, offset, and status, including defaults and meaning. The description only briefly restates that filtering is by Space or status and pagination via limit/offset, adding no syntax or detail beyond the schema. This matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb (List), resource (wiki pages), and enumerates the returned fields (ids, titles, summaries, Space, status, last-modified). It explicitly distinguishes this from read_page by positioning itself as the tool to find the page id that read_page needs.

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

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

It gives clear usage contexts: 'browse what the wiki already covers before writing a page' and 'find the page id read_page needs.' It also notes filtering and pagination. However, it does not explicitly state when not to use it (e.g., for reading content) beyond the implicit contrast with read_page.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavior annotations cannot: pending captures are memories that do not yet 'count' until reviewed, which tells the agent the result set is provisional and action is required downstream. It stops short of describing ordering or result shape.

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 with the purpose front-loaded, then usage, then hand-off tools. Every clause carries routing value with no repetition of schema content.

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 with no output schema, the description covers what the resource is, when to invoke it, and the accept/reject follow-up. Only the return shape (fields per pending capture) is left implicit, which is a minor gap given the annotations and fully documented schema.

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

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

Schema description coverage is 100%, and both `limit` (default 20, tunable for full audit vs quick check-in) and `space` (auto-detected if omitted) are fully documented there. The description adds no parameter semantics of its own, 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+resource and defines the domain concept: 'List pending captures: memories waiting for review before they count.' That distinguishes it from list_pending_imports and list_pending_revisions by using the 'captures'/'memories' framing, though it never explicitly contrasts with those near-identical siblings.

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 trigger ('Use when the user wants to audit what got captured') with concrete user phrases, plus the follow-up path: `confirm_memory` to accept, `forget` to reject. An agent knows both when to call this and what to do next with the results.

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 readOnly/idempotent/non-destructive annotations by disclosing the returned fields (id, vendor, stage, processed/total counts) and the purpose of the id for disambiguating concurrent imports. It also discloses a transport-dependent behavior: source_path appears only over local stdio, while remote HTTP yields a progress summary without filesystem paths.

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, each earning its place: purpose first, gating condition second, output shape and transport differences last. No redundant restatement of the title or annotations.

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 explicitly and also covers the environment-specific variance in results. Combined with rich annotations and a zero-parameter schema, an agent has everything needed to decide when to call this and how to interpret the response.

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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly presents this as a no-argument listing call without implying any hidden filters.

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

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

States a specific verb and resource ('List in-flight chat-history imports') with an explicit scope of what is included (awaiting processing or completion). This clearly separates it from siblings like list_pending_revisions, list_refinements, and list_pending, which cover different pending object types.

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 concrete triggers ('what imports are running, whether an export is done, or requests import progress') and a restrictive 'Use only when' framing that excludes other cases. It stops short of naming alternative tools, so an agent must infer what to call for non-import status questions.

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 read-only safety, and the description adds operational context they cannot: acceptance is local-only and accept_revision is unavailable over remote HTTP MCP, plus default 50 / max 500 result capping. These are exactly the kinds of constraints an agent needs before routing a user toward an approval flow.

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 purpose, then usage triggers, then return-item fields, then pagination — a sensible order. It is one dense paragraph, and the parenthetical accept_revision caveat is slightly wordy, but no sentence 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?

With no output schema, the description compensates by naming the fields each item carries (target_source_id, revision_content) and explaining how target_source_id feeds the next step. Pagination limits and remote-HTTP limitations are also covered, leaving no obvious gap for a zero-required-param list tool.

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

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

Schema description coverage is 100% and the single `limit` param is fully documented there, including the default and clamp. The description's 'default 50, max 500' merely restates the schema rather than adding format or interaction detail, 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?

States a specific verb and resource ('List memories awaiting human accept/dismiss because a newer version was proposed') plus the mechanism ('Protected tier supersede'), which separates it in meaning from list_pending, list_pending_imports, and list_refinements. It never names those siblings explicitly, so the differentiation is inferential rather than declared.

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 concrete user-utterance triggers ('what revisions are pending', 'show me memories awaiting approval') and spells out the downstream workflow rule: pass target_source_id to accept_revision only after the user explicitly approves that item. It also names accept_revision and the accept/dismiss alternatives, so the when-to-use and when-not-to-act boundary 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds genuinely new behavioral context: a prohibition on ambient polling and a gating rule requiring an unambiguous user decision before the accept/reject siblings are invoked. It stops short of describing ordering or what an empty queue looks like.

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 primary rule and the anti-polling prohibition before the mechanics. Dense and nearly waste-free, though the 'filter by action and bound with limit' clause largely duplicates schema text.

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

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

For a two-param read-only list tool with no output schema, the description supplies the missing return-value hint ('typed actions and payloads, including vocab_promote') and the critical workflow gating. Only the empty-result and ordering semantics remain unstated, a minor gap given how much annotations and schema already carry.

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 both parameters are already fully documented, including the accepted action values and the 500 default/max. The description only restates 'Filter by action and bound the result with limit' and adds no syntax or format detail beyond the schema, making baseline 3 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 and resource ('List pending daemon refinement proposals') plus the payload shape ('typed actions and payloads, including vocab_promote'). It does not explicitly name the confusable siblings (list_pending, list_pending_revisions, list_pending_imports), so differentiation relies on the word 'refinement' alone.

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 ('only when the user explicitly asks to inspect or review the proposal/refinement queue'), when not to ('never poll this queue ambiently'), and what to pair it with afterwards ('accept_refinement or reject_refinement only after an unambiguous item-level user decision'). This is a full when/when-not/next-step specification.

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, so the description's added value is defining the near_duplicate semantics (stored anyway but logged) and the returned fields (reason codes, detail, similarity). This is meaningful context beyond the safety profile, though it doesn't discuss volume/pagination limits of the list.

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 what is listed, then the near_duplicate clarification, then usage. Dense but each clause carries information; slightly long but no filler.

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

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

With no output schema, the description correctly summarizes return contents (reason codes, detail, similarity). It omits behavior of unlimited queries (default/clamp) but that is covered in the schema, leaving the definition complete for an agent to call it.

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 both limit and reason are fully documented there (default 50, clamp 1..=500, example reason codes). The description only restates that optional limit and reason filters narrow the audit, adding no syntax or behavior beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('List quality-gate flags and rejections') and then defines the two distinct categories it covers: discarded memories and stored-but-logged near duplicates. An agent can distinguish this audit tool from the retrieval siblings without reading 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?

Explicitly scopes usage with 'Use only to diagnose a missing capture, a flagged near duplicate, or when the user asks what Wenlan rejected,' which tells the agent when-not to reach for it. It stops short of naming a specific alternative sibling (e.g. recall) for normal lookups, so not a full 5.

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 beyond the annotations: mark/confirm require `version` and are refused if the basis note moved on ('nothing changes' semantics per schema), remove drops the reliance, and changes are local stdio only. Idempotency and non-destructiveness are already declared by annotations, so no credit there, but the version-refusal behavior is genuinely useful.

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 purpose, then the trigger condition, then compact per-action clauses. No filler; the telegraphic style stays readable.

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

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

There is no output schema, and the description does convey what diff returns ('the text relied on next to the text now'), but it says little about what mark/confirm/remove return or what a pending basis looks like after each action. Adequate for a small 4-param mutation tool but not exhaustive.

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 description's version note ('the basis note's page.version from read_page') largely repeats what the schema already says, including the warning that it is not the citing page's version. 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?

Opening sentence gives a specific verb and resource: tracking a wiki page's reliance on another page. Implicitly distinguishes from the code-facing sibling page_code_basis by framing it as a text/basis-note relationship, though it never names that sibling.

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

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

Explicit trigger: 'Use when read_page, list_pages or recall shows a `pending` basis', and each action word is given a one-line role. It does not say when not to use it or route to page_code_basis for code dependencies, which is the main missing piece.

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 idempotent=true and destructiveHint=false; the description adds the real side effect that Wenlan re-reads the file, recomputes the fingerprint and flips the row to `ok`, plus the local stdio constraint. It does not describe the response payload, and 'remove: drop the reliance' sits close to the destructive=false hint without clarifying that only the linkage is dropped, not the page.

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?

Short and front-loaded: what it settles, then the two actions, then the identifying fields, then the transport caveat. The telegraphic, backtick-heavy phrasing is dense but every sentence carries information.

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

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

For a 6-required-param mutation tool with no output schema and full annotation coverage, the description covers state transitions, alternatives and environment limits. The one gap is what happens on success/failure (return value, whether the row id or new fingerprint comes back).

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

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

Schema coverage is 100% and the per-field descriptions already say 'exactly as read_page returned it'. The description's only addition is that repo_root, path, line_start, line_end are the row's composite identity, which is marginal above 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 ('settle') and resource ('a code_basis row') plus the precondition states (`pending`, `unavailable`, `moved`) and the required prior step ('after reading the code'). It also names the sibling it is not: write_page, when the page no longer holds.

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 agent: use `confirm` when the page still holds, rewrite with write_page when it does not, and `remove` to drop the reliance. The triggering row states are named and the 'read the code first' prerequisite is stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real value on top: the full return contents, the 'in one call' hint that no pagination is needed, and the warning that the id is opaque and must never be guessed from a title. It stops short of noting what happens on a missing/stale id, which keeps it off a 5.

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

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

Three sentences, front-loaded with the payload, then the usage routing, then the id caveat. No repetition of annotation or schema content and no filler.

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

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

With no output schema, the description compensates by enumerating exactly what comes back (title, body, status, Space, cited memories). Combined with 100% schema coverage and full annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the ASCII/hyphen format rules and the session format. The description only reinforces the opaque-id constraint already in the schema, so it adds little beyond structured data — baseline 3.

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

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

States a specific verb (read) and resource (one wiki page) plus the exact payload returned: title, body, status, Space, and cited source memories. It explicitly contrasts with list_pages and recall, so an agent can distinguish it from snippet-returning siblings 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?

Gives an explicit trigger: 'Use it after list_pages or recall when the user wants the page itself rather than search snippets.' That names both the sequencing and the alternative behavior, leaving nothing to infer about when this tool is the right pick.

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, which could confuse an agent about a search tool; the description resolves this by explaining that search 'records the query and accessed memory IDs in local activity history for auditability; it does not rewrite stored knowledge.' It also discloses the rerank latency tradeoff and the WENLAN_RERANKER_ENABLED=1 daemon prerequisite with its silent fallback behavior — none of which the annotations or schema fully capture.

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 purpose and triggers, then layers query-writing advice, filtering strategy, and the rerank tradeoff in short scannable sentences. It runs a bit long for a search tool, and the rerank detail is partially redundant with the schema's own description of that parameter, but no sentence 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?

Six parameters with an unusual audit side effect and a feature-gated quality flag demand more than a one-liner. The description covers trigger conditions, query formulation, filter-vs-query tradeoff, the side effect that explains the write-ish annotation, and the sibling boundary — enough for correct invocation without an output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real strategy beyond the schema: write queries as natural language because the engine does semantic matching, and prefer filters over longer queries when result sets are too large. The rerank flag's prerequisite is restated with its failure mode, though per-parameter meanings live mostly in the schema.

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

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

Opens with a specific verb+resource ('Search memories by query') and immediately differentiates from the closest sibling: 'To resume work from a Space-owned project snapshot, use brief instead.' An agent can route correctly 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 concrete triggering phrases ('do you remember', 'what do you know about', 'look up') plus the proactive condition 'when you need a specific fact before acting.' It also names the alternative tool and the condition that selects it, and explains the fallback strategy (add filters rather than lengthen the query) when results are too broad.

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: it explains that destructiveHint means the proposal becomes 'dismissed and terminal, so it cannot be retried' while explicitly scoping what is NOT destroyed ('does not delete or overwrite the underlying memory or page'). It also discloses an environment constraint the annotations cannot express — unavailable over remote HTTP MCP transport, local stdio only.

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, each carrying distinct load: purpose plus precondition first, then terminal-state consequences and what is untouched, then no-op and transport caveats. No repetition and 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 single-parameter, non-idempotent-looking mutation with no output schema, the description covers the precondition, the irreversible consequence, the blast radius, and the transport restriction. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents the single id parameter. The description still adds useful semantics by clarifying the id must reference an item from a listed refinement proposal and that exactly one is operated on, disambiguating it from memory or page ids.

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 scope: 'Reject one listed refinement proposal by id.' An agent can immediately tell this is the negative counterpart to accepting a refinement. It never names the sibling accept_refinement explicitly, so differentiation is by inference from the verb rather than by direct contrast.

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?

'only after the user gives an unambiguous item-level reject decision' sets a clear, strict precondition for calling, and 'Skip or cancel is a no-op' tells the agent when not to bother. It stops short of naming the alternative tool (accept_refinement) for the opposite decision, so the routing guidance is strong but not fully 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?

Adds context beyond the annotations: the optimistic-concurrency contract (expected_version prevents renaming a page changed since read), the blast radius (title only, id and content preserved), and a hard deployment constraint ("unavailable over remote HTTP MCP transport (local stdio only)") that no annotation conveys. The destructiveHint=true flag is conservative rather than contradicted — the description clarifies exactly what is and is not mutated.

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 carrying a distinct load: trigger, required-input provenance, effect, and environment/exclusion. The usage constraint is front-loaded before the caveats, so an agent can decide to call or skip it from the first clause.

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

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

For a 3-required-param mutation tool with no output schema, the description covers trigger, preconditions, effect on state, the read-modify-write pattern needed to obtain expected_version, and a transport-level availability constraint. An agent has everything needed to invoke it correctly or route to write_page instead.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance guidance the schema does not: page_id and expected_version should come from "the latest page result," and it explains the purpose of the version field as a race guard. Minor overlap with the schema's own expected_version text keeps it from 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?

States a specific verb and resource ("Rename an existing page") and immediately bounds the scope ("changes the title only and preserves the page id and content"). It also distinguishes itself from the nearest sibling, write_page, which is a crowded neighborhood of page-mutation 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 an explicit trigger ("only when the user explicitly asks to change its title"), an explicit anti-trigger ("Do not call this during distillation, synthesis, or content refresh"), and names the alternative to use instead ("write_page keeps an existing title when refreshing"). Nothing about when-to-use 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 beyond the annotations by explaining the actual replacement semantics ('saving the same url replaces it') and that no fetching or syncing happens ('it is a snapshot; Wenlan does not fetch or sync the original'), which concretizes the destructive/idempotent hints. It does not mention permissions, failure modes, or what the call returns, so it stops short of fully rich behavioral context.

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

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

The opening sentence defines the tool and its scope, then the sibling routing rule, then the content rule, then the behavioral caveat — each sentence carries distinct information with no repetition. Nothing is padded.

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

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

For a six-parameter write tool with no output schema, the definition covers what it does, what to feed it, how duplicates behave, and what it explicitly does not do (fetch/sync). The remaining gaps (return value shape, permissions) are minor and largely carried by annotations and the 100%-covered schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaningful emphasis on content semantics ('the original text as you read it... Not your summary') and reinforces the url-is-identity rule. It says nothing extra about space, create_only, or source_label beyond the schema, limiting it to a modest lift.

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

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

States a specific verb and resource ('Save a document') plus the concrete source types it covers (email, Notion/Drive page, Slack thread, article). It also names the sibling it competes with ('use this instead of capture when the content has a link'), so an agent can pick between them 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?

Explicit routing rule versus the alternative ('instead of capture when the content has a link'), an exclusion ('never bulk-copy an inbox or channel'), and a content-quality rule ('pass the text as read, not a summary'). Both when-to-use and when-not-to-use are stated.

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

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

Adds real context beyond the annotations: it discloses upsert semantics ('The first update creates the Brief'), the optimistic-concurrency guarantee ('conflicts are reported, never silently overwritten'), and an environment constraint ('Local stdio only'). The annotations already cover safety/idempotency, but this clarifies the version-guard failure mode that annotations cannot express.

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: what it does, the required read-before-write discipline, then the create-on-first-use and stdio constraints. Nothing is repeated or padded.

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

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

Covers purpose, ordering, concurrency behavior, and environment restrictions for a mutation tool with no output schema. Minor gaps remain — e.g. partial-failure behavior when a batch of mutations only partly succeeds — but nothing essential to a correct call is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description explains the *purpose* of expected_version (reuse versions from the last read) and frames mutations as an ordered list of tagged kinds, which is more than the schema's structural enumeration alone.

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 concrete verb+resource pair ('Hand off to the next session by updating the Space Brief') and then enumerates the exact operations (replace summary, add/edit/move/gate/complete items). This clearly separates it from the read-only sibling 'brief' and from unrelated siblings like write_page or capture.

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 prerequisite workflow: 'Read brief first and reuse its brief_version and item versions', which tells the agent the ordering relative to the sibling 'brief' tool. It doesn't spell out when *not* to use it or what to do on conflict beyond 'conflicts are reported', so it falls just short of a 5.

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 far beyond the annotations (destructiveHint=true, idempotentHint=false) by disclosing exactly what is destroyed and preserved: content + source_memory_ids replaced, stale_reason cleared, page_id and created_at preserved, version bumped for wikilink stability, atomic DB + on-disk <slug>.md projection. It also documents refusal semantics on expected_version mismatch (nothing changed), review_required staging, and the local-stdio-only transport limit.

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

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

Purpose and creation path are front-loaded, but the body is a dense, run-on block that repeats itself ('from the `stale_pages` block in distill output' and the expected_version refusal appear twice). Nearly every sentence carries information, yet the lack of structure makes it harder to parse than it needs to be.

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 12-parameter, destructive, versioned tool it covers creation, refresh, atomicity, version guard, review staging, basis/code_basis and transport constraints. The gap is return values: with no output schema, the description only incidentally mentions that the reply lists bases/code bases, and says nothing about the returned page object or version.

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

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

Schema coverage is 100% and the schema descriptions are already rich, so baseline is 3; the description still adds meaning, e.g. why expected_version exists ('if the page moved on, the write is refused... so re-read and retry'), that basis is notes-only while source_memory_ids is memories-only, and refresh carry-through of existing source lists. Some of this duplicates the schema text rather than extending it.

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 ('Create or refresh a wiki page') and immediately separates the two modes by page_id presence. It also names the siblings it is not (rename_page, delete_page) and the anti-pattern (delete + recreate), so an agent can route correctly 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?

Explicit when-to-use ('When the user asks to turn something from this conversation into a page'), when to create vs refresh (omit page_id vs pass page_id), and concrete alternatives: rename_page for title changes, read_page before refresh, never delete_page + recreate. Exclusions and prerequisites are all stated.

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