Workfile

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the key behavior of aggregation (from multiple source types: direct relations, conventions, incidents, project context) and boundedness ('compact context bundle', 'limit' defaults). However, it doesn't describe what happens when no data is found for a category, or how current the data is. With strong annotations present, a 3 is appropriate.

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

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

Two sentences, zero waste. The first sentence states the purpose with concrete content types; the second provides an actionable usage recommendation. Every phrase earns its place, and the description is front-loaded with the most important 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?

The tool outputs a context bundle (with an output schema present), so the description need not explain return values. It enumerates the source types that feed the bundle, names the intended workflow use-case, and the annotations + schema cover the safety and parameter dimensions. For a read-only aggregation tool, this is complete.

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

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

Schema coverage is 100%, so the input schema already documents both parameters (cardId and limit) fully. The description adds value by explaining that the bundle is 'centred on' the card and is 'compact' (bounded), which clarifies the semantic role of the limit parameter beyond its schema description. However, the param-level value-add is modest since the schema is already complete, giving a 4 rather than 5.

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

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

The description uses a specific verb+resource ('Build a compact context bundle around a card') and clearly enumerates what it aggregates: direct relations, active conventions, open incidents, and active project context. It clearly distinguishes itself from sibling tools like project_get_record or project_search, making the purpose unmistakable.

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

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

The description explicitly states when to prefer this tool: 'Prefer this over reading records one by one before working on a card.' This gives the agent a clear decision rule and differentiates from sibling tools that fetch single records or search. It explains the intended workflow context (working on a card) rather than just what the tool does.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description adds meaningful behavioral context: the card 'survives' (the archive is reversible via project_card_reopen), which is genuinely new information beyond annotations. It doesn't discuss permission/auth requirements, but given the annotation coverage and that this is a state-change operation, the transparency is decent.

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 crisp sentences with zero filler. The first sentence states the action, the second packs the precondition, survivability, and reversibility notes into an efficient caveat clause. Everything earns its place.

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

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

Given the tool has an output schema (so return format is handled), full schema coverage for 2 params, and clear annotations (destructiveHint=true), the description covers the essential semantics: what it does, which cards qualify, and reversibility. It could mention concurrency/revision implications or permissions, but for a single-item state-change tool this is reasonably complete.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description adds value by confirming the id parameter must reference a done/discarded card, aligning with the schema. The expectedRevision parameter is not elaborated in the description, but the schema covers its semantics (concurrency check) thoroughly, so the baseline 3 is exceeded slightly by the id constraint reinforcement.

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 title 'Archive a closed work card' plus description 'Move a closed card to the canonical archive directory' clearly state the verb (archive/move) and resource (closed card). It doesn't explicitly distinguish from siblings like project_card_write or project_card_reopen, but the domain-specific 'canonical archive directory' adds clarity. It drops slightly from a 5 because it doesn't name the sibling alternatives for differentiation.

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

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

The description states the precondition ('Only done and discarded cards can be archived') and notes the reversible nature via project_card_reopen, giving clear context. It doesn't explicitly say when NOT to use it or name alternatives as the when/not alternatives, but the inversion (reopen undoes) implies the lifecycle placement.

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

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

Annotations already declare non-readonly and non-idempotent, so the description needn't repeat that. It adds valuable context: the claim mutates state (moves to 'doing'), enforces exclusivity (refused unless forced), and involves concurrency protection. It doesn't describe the return format or outcome details, but with annotations covering the basic safety profile plus output schema present, this is solid.

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 filler. Front-loads the core action and purpose, then adds the critical exclusivity caveat. Every sentence earns its place.

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

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

For a complex concurrency-sensitive tool with 6 parameters, dedicated annotations, and an output schema, the description is complete. It captures the essential mutating behavior, exclusivity rules, filesystem scope purpose, force/override semantics, and timing guidance. The output schema and rich parameter descriptions handle the rest.

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 parameters are richly described in the schema itself. However the description adds meaningful semantics beyond the schema: it frames scope as the mechanism 'stopping two agents editing the same files' and clarifies that claim refusal semantics are the core behavior. The description and schema together fully explain the 6 parameters.

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?

Description clearly states the verb, resource, and concurrent effects: 'Claim a card for an actor, move it to doing and optionally declare the filesystem scope that will be changed.' This distinctly differentiates it from siblings like project_card_release, project_card_transition, and project_card_patch by naming the claim + move-to-doing + scope behavior.

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

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

Explicitly states when to use it ('Claim before editing anything the card covers') and the exclusivity semantics ('another actor's claim is refused unless forced'), giving clear when/when-not guidance versus the sibling release and patch tools.

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 (it mutates), which the description's 'Create' and 'mints a new record' wording confirms—no contradiction. The description adds the concurrency-safe stable ID behavior as useful context. However, as a creation tool with an output schema, it doesn't disclose return behavior or whether partial failures occur, and 100% schema coverage means the description carries moderate additional burden beyond 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 two concise sentences with no filler. The operational guidance ('search first') is front-loaded and adds value. It could arguably mention the distinction from project_card_write explicitly, but the existing structure is tight and purposeful.

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?

Given a complex 16-parameter tool with an output schema and annotations present, the description covers the key operational concern (search-first to avoid duplicates, concurrency-safe ID). The nuanced project-declared values (area, axes) are delegated to project_workspace which is correctly referenced. It's reasonably complete for a create operation, though could note what the canonical-creation invariant ensures about duplicates.

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 documents all 16 parameters thoroughly. The description doesn't add parameter-level meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting, though the description's comment about project_workspace for accepted area/axes values aligns with what schema already notes.

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 clear verb+resource ('Create one canonical Work card') with a distinctive attribute ('concurrency-safe stable ID'). It distinguishes from project_card_write (which shares the 'create' domain) by emphasizing 'one canonical' card with concurrency safety. However, it doesn't explicitly name the sibling it differs from, leaving some differentiation implicit.

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

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

The phrase 'Search first: this mints a new record rather than finding an existing one' provides explicit usage guidance, implying the agent should check for existing cards (via project_next or project_search) before calling create to avoid duplication. This gives clear context on when this tool is appropriate. It doesn't explicitly list excluded sibling tools, but the guidance is actionable.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered by structured data. The description adds the filtered-list semantics and the 'use before starting work' workflow context. The openWorldHint=false is slightly in tension with the description implying exhaustive results, but this is reasonable for a filter-based read tool.

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

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

Two tight sentences: the first enumerates the filter dimensions in a compact list, the second states usage context and the alternative tool. Zero waste, all information earns its place.

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

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

For a 11-parameter read tool with an output schema and strong annotations, the description is complete enough. It explains the filter scope, provides usage timing, and names the alternative. No nested-object complexity or undocumented safety concerns. Could mention pagination behavior (limit/offset) but the schema documents those defaults clearly.

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

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

Schema description coverage is 100%, with each parameter having a detailed description including enums for type, status, and priority. The description names the filter dimensions but adds little beyond the schema. Baseline 3 is appropriate since the schema carries the full burden of parameter documentation and does so well.

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 verb (list) and resource (work cards) with explicit filter dimensions (status, area, type, priority, parent, claim). It distinguishes from sibling project_search by noting the full-text alternative, and name/title reinforce the same purpose without contradiction.

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

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

'Use before starting work' provides clear contextual guidance for when to invoke this tool, and it explicitly names project_search as the alternative for full-text queries. It doesn't enumerate every sibling's differentiation, but the key alternative is called out, which is sufficient given the schema provides exhaustive filter options.

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 (mutation) and destructiveHint=false, which the description supports by explaining it appends rather than rewrites. The description adds value by explaining concurrency safety and the "created if it does not exist" section behavior via the schema. It doesn't mention idempotency implications or whether the timestamp is server-side, but annotations cover the core safety profile.

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

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

Two sentences, front-loaded with the core action, and zero filler. Every phrase earns its place — the timestamped-line detail, the cost comparison, and the concurrency safety are all high-value.

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

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

For an append-only tool with 4 params (100% schema coverage) and an output schema, the description plus schema fully covers the behavioral contract. The concurrency-safety note addresses the key risk of a mutation tool, and the heading-creation behavior is documented in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the "timestamped" behavior and the "safe for concurrent writes" framing but doesn't add details about parameter formats or constraints beyond schema descriptions, which already document actor defaulting and section creation.

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?

Description says "Append one timestamped line under a heading" — specific verb (append), specific resource (card), and specific mechanism (timestamped line under heading). It distinguishes from sibling card_write and card_patch by emphasizing the append-only, cheap, concurrent-safe nature.

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?

Description says it's "cheaper than rewriting the body and safe when two agents write at once," which signals when to prefer this tool over writing/patching the body. It doesn't explicitly name the alternative tools (card_write/card_patch) or give exclusions, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds valuable behavior not in annotations: optimistic concurrency semantics — that expectedRevision causes refusal on stale writes and that an empty axes value clears an axis. The 'only the keys present are touched' partial-update behavior is also disclosed.

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

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

The description is two dense, front-loaded sentences with zero filler. Every clause conveys load-bearing information: the operation, the concurrency model, the expectedRevision condition, and the axes clearing semantics. The schema descriptions are also concise and informative. 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?

The tool has 3 params (100% schema coverage), nested objects, an output schema, and clear annotations. The description, combined with the rich schema and annotations, fully covers the patch mechanics, concurrency behavior, and axis handling. It's complete for the tool's complexity. The only minor gap is it doesn't explicitly preview the output, but the output schema exists so that burden is transferred.

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

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

Schema coverage is 100%, so the schema already documents all three parameters well. The description adds value beyond the schema: it clarifies that an empty axes value clears an axis, names the exact shape '{ name: value }' for changes.axes, and explains the concurrency-check behavior of expectedRevision beyond its schema text. This exceeds the schema-only baseline of 3.

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

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

The description says 'Patch allowed card metadata using optimistic concurrency' — a specific verb (patch) plus resource (card metadata) plus a defining mechanism (optimistic concurrency). It clearly distinguishes itself from siblings: the schema notes status belongs to project_card_transition and body to project_card_write, and the description explains axes placement, disambiguating from project_card_write and others.

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 guidance: 'Use expectedRevision whenever the card was read earlier' and 'Declared axes go in changes.axes'. The schema additionally directs status changes to project_card_transition and body changes to project_card_write, naming concrete alternatives. This is strong when-to-use versus alternative-tool guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the mutation profile is known. The description adds valuable behavioral nuance: the status handling rule that 'doing becomes next because active work without a claimant is a contradiction' and that doing is refused as an explicit target. The status-field description (inside params) explains the done-not-demoted edge case. Describes the force/actor interaction implicitly. Good behavioral context beyond annotations, though it could note the audit/permission implications of force more explicitly.

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 concise sentences front-load the purpose and trigger condition. No wasted words. Every sentence earns its place, and the nuanced status behavior is deferred to the parameter schema where it belongs rather than cluttering the description.

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

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

For a mutation tool with idempotence declared and full schema coverage plus an output schema, the description is largely complete. It covers the action, the trigger, and the core behavioral twist (status handling). Could arguably add more on the force/reason authorization flow, but with 100% schema coverage and output schema present, the description carries adequate weight. Good completeness for its complexity.

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

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

Schema description coverage is 100%, so all 6 parameters are documented in the schema. The description adds specific behavioral context for the status parameter: the exception that a card just moved to done is not demoted by releasing, and the doing-becomes-next rule. This is genuinely useful semantic guidance beyond the raw enum/schema text. However, the description itself doesn't enumerate each parameter, relying on the full schema coverage, so baseline 3 plus the status nuance earns a 4.

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 action: 'Release your claim on a card and move it out of doing.' This is a specific verb+resource with clear scope. It distinguishes from sibling tools like project_card_claim (the inverse operation) and project_card_transition by focusing on claim release specifically. Clear and actionable.

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?

'Call when work stops, finished or not' provides clear trigger context for when to use the tool. It distinguishes releasing from simply transitioning by noting it moves cards 'out of doing.' While it doesn't explicitly name alternatives or when-not-to-use, the purpose is clear enough that the agent can differentiate this from claim, transition, and patch operations. Lacks explicit exclusions naming sibling alternatives, hence not 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?

Annotations already declare readOnlyHint=false, destructiveHint=false. The description's key value is the 'ID never changes' guarantee and the mechanism (moving out of archive directory into a live status). However, it doesn't disclose things like whether reopened cards retain notes/memory, or what happens to the prior done/archived status beyond the archive flag. With annotations covering the safety profile, this is adequate but not rich.

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

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

Two tight sentences with zero waste. The first delivers the purpose and action; the second delivers the critical behavioral guarantee (ID stability). Front-loaded and efficient.

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?

The output schema exists and schema coverage is 100%, so the description doesn't need to detail returns. The key forward-looking guarantee (ID never changes) is stated. It could briefly note that reopening impacts references for the status param or the actor field, but the essentials are covered for this moderately complex tool.

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

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

Schema coverage is 100%, so all 4 params are documented. The description adds meaningful context on the 'id' param (the one that never changes) and complements the 'status' enum by clarifying the card is 'brought back into a live status.' It reinforces the expectedRevision semantics through the 'write is refused if no longer matches' phrasing, adding practical value beyond the schema's 'skip the check' note.

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

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

Clear verb+resource: 'Move an archived card back out of the archive directory and into a live status.' Specifies what it does and the key net effect (the ID never changes, references keep resolving). While it's clear and distinct from siblings like project_card_archive (the inverse action), it doesn't explicitly name a sibling as a contrast, so not quite a 5.

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

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

The description implies this is used after project_card_archive, and states the ID-stability benefit. However, it doesn't explicitly say when to use this versus project_card_transition or project_card_write (which also affect status), nor state any preconditions or exclusions for when reopening is appropriate.

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 and destructiveHint=false, so the tool is known to mutate but not destroy. The description adds valuable semantics beyond annotations: moving to 'doing' claims the card for the actor, 'done' requires evidence it ran (not a commit). This adds protocol-level behavioral context that annotations alone don't 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?

Three sentences, front-loaded with the core action and then targeted clarifications on the most semantically-loaded statuses (doing, review, done). No wasted words. Could arguably be even tighter, but every sentence earns its place.

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

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

The tool is moderately complex (8 statuses, 5 params) with a full output schema and 100% schema coverage. The description covers the key conceptual distinctions (claim semantics, verification requirement, evidence standard). The mutating-but-not-destructive profile is clear, and the complexity is well addressed for an agent selecting transitions.

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 status enum and parameter descriptions are complete. The description adds meaningful value beyond the schema: it clarifies the claim-on-doing behavior and the evidence requirement for 'done', which enrich what the enum descriptions alone convey. The description reinforces but doesn't restate the full enum.

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

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

The description uses a specific verb ('Move') and resource ('a card') with clear target (''another protocol status'). It names what the tool does. However, it doesn't explicitly distinguish from siblings like project_card_claim, project_card_release, or project_card_reopen, though the status-enum and claim semantics provide implicit differentiation.

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

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

The description clarifies nuanced semantics of moving to 'doing', 'review', and 'done' (claiming for actor, verification, evidence-of-run). It gives implicit context but doesn't explicitly say when to use this vs alternatives like project_card_claim/release, nor state exclusions. Sibling differentiation is implied through status semantics rather than 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 declare destructiveHint=false, but the description and schema clarify this is an overwriting operation ('The complete new Markdown body. This overwrites'). The schema's expectedRevision parameter explains the concurrency behavior ('The write is refused if it no longer matches, so a concurrent edit is reported rather than overwritten'), which adds meaningful behavioral context beyond the annotations about the destructive/overwrite semantics and lock/version checking.

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 two tight sentences: one states the primary action and mechanism, the second gives the sibling alternative. Zero wasted words, and the overwrite warning is delivered in the schema. Perfect front-loading of the core purpose.

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?

The tool is a mutation with a concurrency-control mechanism, and the schema + annotations cover the essential context well. The description explains the protocol lock/revision behavior and names the append alternative. The output schema exists, so return-value documentation isn't needed. Slight gap: no mention of what happens if the id doesn't exist, but the revision check covers the main failure mode.

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

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

Schema description coverage is 100%, so all three parameters (id, body, expectedRevision) are documented in the schema itself. The description adds marginal value ('This overwrites, so read the card first' clarifies body semantics beyond a plain field label). Per the rubric, baseline 3 is appropriate when the schema already handles parameter documentation fully.

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 clear verb+resource+action: 'Replace the Markdown body of a card' with a specific mechanism ('under the protocol's lock and revision check'). It distinguishes from sibling project_card_patch (partial vs full replace) and explicitly points to project_card_note as the append alternative. This clearly differentiates from 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?

The description explicitly names the alternative tool for appending ('Use project_card_note to append instead') and the schema hints to read the card first ('read the card first unless you intend to discard what is there'). The expectedRevision parameter semantics also tell the agent when to use it and what happens on mismatch, giving clear when-to-use and excluded-behavior 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 declare readOnlyHint=false, so the mutating nature is already signaled; annotations do not contradict. The description adds behavioral context: fragments are 'unreleased' (they accumulate until a release tool consolidates them) and 'atomic', giving the agent a sense of scope and lifecycle. It doesn't detail response format or failure modes, but output schema and annotations cover some of this. Slight gap on what happens after creation, but the note about 'unreleased' is valuable.

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

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

Two sentences, no filler, front-loaded with the core purpose. The second sentence adds genuinely useful operational guidance (granularity and timing). Could arguably be trimmed but every word earns its place and nothing is redundant with the schema.

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

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

With 10 parameters but full schema coverage and a present output schema, the description's job is modest. It communicates the invariance rules (atomic, unreleased, timing) which the schema cannot express. It doesn't spell out the relation types fully, but the schema fields (cards, decisions, related, issues) cover that. Reasonably complete for a create-oriented tool.

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

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

Schema coverage is 100%, so all 10 parameters have structured descriptions already. The description adds the 'atomic' and 'unreleased' framing that connects to title/body semantics, but doesn't itself explain individual parameters. Per the baseline rule, schema is doing the heavy lifting, so 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?

The description states a specific verb+resource ('Create an atomic unreleased changelog fragment') and adds clear semantics: one fragment per user-visible change, written when the change lands rather than when release is cut. It also mentions relating to cards, decisions, or other records, which distinguishes it from siblings like project_changelog_patch (edits existing) and project_changelog_list (lists).

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

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

The description gives clear timing guidance ('written when the change lands rather than when the release is cut') and the atomicity rule ('One fragment per user-visible change'). It implies the creation use-case distinct from patch/release siblings, though it doesn't explicitly say 'use list/patch instead when...'. The timing and granularity advice is useful, context-rich guidance by name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing this as a safe read operation. The description adds the 'released' filtering semantic (consumed by release vs unreleased) as context beyond what annotations provide. For a read-only listing tool with strong annotations, the coverage is adequate.

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

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

A single compact sentence covering purpose and filter dimensions. It's efficient and front-loaded, though the enumerated filters in the description are implied rather than explicitly mapped to parameter names, which would add marginal clarity without bloating length.

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 an output schema present (has_output_schema=true), so return structure doesn't need description coverage. With 100% param schema coverage and read-only annotations, the tool is reasonably self-documenting. The description could mention the released/unreleased distinction as the core listing dimension, but overall completeness is good for a listing tool.

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

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

Schema coverage is 100%, so all 6 parameters have descriptions in the schema itself. The description adds a collapsed enumeration of filter dimensions (type, area, visibility) mapping to 3 of the params. The 'released' boolean parameter is documented in the schema but not surfaced in the description, which would have been helpful. Baseline 3 plus the filter-dimension synopsis merits a 4.

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 it lists unreleased change fragments and cut releases, filterable by type, area, or visibility. This distinguishes it from sibling changelog tools (add, patch, preview, release) which are mutation or preview operations. However, it doesn't explicitly contrast against sibling changelog_list variants, so it's clear but not fully differentiating.

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

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

The description implies usage for listing/filtering changelog content but provides no explicit when-to-use guidance or exclusions. Siblings like project_changelog_add, project_changelog_patch, project_changelog_release are clearly mutations, so listing is the natural read operation, but no alternative tools are named and no exclusion criteria given.

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 (it's a write), idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the optimistic-concurrency mechanism and the release-boundary constraint ('afterwards the text belongs to that release'). This directly explains what happens in the concurrent-edit case and the lifecycle boundary.

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 crisp, front-loaded sentences with zero wasted words. The first sentence states the purpose plus the key concurrency mechanism; the second sentence nails the critical lifecycle boundary. Every clause earns its place.

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

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

Given the moderately complex signature (a nested object parameter, an optional concurrency-check param) and the presence of an output schema, the description covers the essential operational semantics. It leaves details of the output schema to the schema itself. Could mention what fields are valid in 'changes' or error behavior, but the schema covers field names and the description covers the partial-update and concurrency semantics.

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's first sentence adds lifecycle semantics for the id parameter context and explains the concurrency-check behavior of expectedRevision. The 'Only the keys present are touched' note clarifies partial-update semantics for the changes object beyond what the schema states, which is valuable for an object parameter.

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

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

The description states a specific verb+resource ('Patch an unreleased changelog fragment') with clear scoping — it operates on 'unreleased' fragments only and explicitly distinguishes itself from the release-related lifecycle ('Only works before a release consumes the fragment'). It differentiates from sibling tools like project_changelog_add, project_changelog_list, and project_changelog_release which are lifecycle peers.

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

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

The description clearly states when the tool works ('before a release consumes the fragment') and its optimistic-concurrency behavior. It could be strengthened with an explicit alternative mention (e.g., adding vs patching a fragment), but the lifecycle constraint provides clear operational guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's a safe read. The description adds the non-mutating scoping ('without mutating the repository'), which reinforces but doesn't heavily extend beyond annotations. No info on output format, but output_schema exists.

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

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

Two tight sentences with zero padding. Each sentence earns its place: one states the action+non-mutating guarantee, the other gives usage context against the sibling. Front-loaded purpose.

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

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

For a simple read-only preview tool with 2 optional params, full schema descriptions, an output schema, and solid annotations, the description is complete. The only slight gap is explaining why visibility values are project-variable, but the description already points to project_workspace for resolution, which is adequate.

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 documents both params well. The description adds context: it explains that visibility is project-declared with varying accepted values, and that omitting fragmentIds previews every unreleased fragment. This adds operational meaning beyond raw 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?

Clear verb ('Render') + resource ('selected unreleased fragments') with explicit non-mutating scope. Names the sibling project_changelog_release as the permanent counterpart, distinguishing it well.

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 'Use to read a release before project_changelog_release makes it permanent,' naming the alternative and the sequential relationship. This gives clear when-to-use guidance against a specific sibling.

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 provide readOnlyHint=false and destructiveHint=true, but the description adds genuine value by explaining the specific destructive consequence: 'the fragments stop being separately editable' and that files are moved into the release directory. This goes beyond the annotation's generic destructive flag, warning the agent that the action is irreversible for those fragments. Combined with the destructiveHint=true annotation, this is solid behavioral disclosure.

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

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

Two sentences, zero waste. Each sentence earns its place: the first states the action and resource, the second adds the critical destructive consequence and preview instruction. Front-loaded and efficient.

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?

The tool has 8 parameters but all are documented in the 100%-covered schema. It has an output schema and destructiveHint annotation. The description explains the core destructive behavior (moving fragments, losing separate editability) and the preview prerequisite. Given the complexity of the release operation, the description is adequate though it could mention what the output schema contains; however, with an output schema present, the description isn't required to explain return values.

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

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

Schema description coverage is 100%, so every parameter is documented in the schema itself. The description adds marginal value: it clarifies the semantics of the key destructive parameter (fragmentIds: 'Omit to consume every unreleased fragment') which is a meaningful behavioral note. However, most parameter meaning is carried by the schema descriptions, 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 clearly states the verb+resource+outcome: 'Consume selected unreleased fragments and create a canonical release record.' It distinguishes from siblings by describing the fragment-to-release mechanism, which is unique among changelog-related tools (project_changelog_add/list/patch/preview don't aggregate fragments into a release).

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

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

The description gives clear context: you consume fragments and create a release record. It implies this is the finalization step and that previewing (project_changelog_preview) is a prerequisite via 'preview first'. It doesn't explicitly name the sibling alternative or give when-not scenarios, but the guidance is strong enough for selecting this tool over changelog add/patch/preview.

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 and destructiveHint=false, indicating mutation but with no safety issue requiring disclosure. The description adds useful context about folder routing behavior and implicitly the creation action. However, it doesn't disclose behavioral traits like whether a DOC ID is auto-generated, what happens with duplicate titles, or whether creating generates review/stale reminders beyond the default review_after semantics mentioned in the schema.

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 core purpose and a single meaningful behavioral constraint about folder placement. No fluff or redundancy. It earns its words, though it could be slightly more explicit about sibling differentiation.

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 12 parameters but 100% schema coverage and an output schema present, the description doesn't need to enumerate everything. It covers the most complex behavior (folder routing) that the schema can't fully express. Combined with the annotations and output schema, this is reasonably complete for a creation tool with a single required parameter.

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

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

Schema description coverage is 100%, with all 12 parameters having descriptions. The tool-level description adds the folder-routing nuance which schema alone wouldn't convey. However, most parameter semantics (kind, status, related, supersedes, etc.) are solely carried by the schema since the description doesn't elaborate further. Baseline 3 is appropriate given full schema coverage.

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

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

The description states a specific verb+resource ('Create a managed Markdown document') and adds a distinguishing feature ('stable DOC ID'). It differentiates from siblings like project_card_create and project_memory_add by focusing on managed documentation, though it doesn't explicitly name alternatives. The 'managed' qualifier and DOC ID point are genuinely informative.

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

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

The description explains the folder placement behavior ('Without an explicit folder the workspace docs.layout decides where it is written'), including that an empty string writes to the root. This gives clear context on when/where content lands, but doesn't explicitly discuss when to use this vs sibling doc tools (e.g., project_doc_patch for edits).

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=true, idempotentHint=true, destructiveHint=false, so the read-only safety profile is already covered. The description adds freshness filtering and the indexed-vs-managed distinction, which enriches behavioral understanding beyond what annotations state. It doesn't contradict 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?

Single sentence, efficient, front-loaded with the core purpose. Minimal waste. The freshness mention is a small ambiguity since it's not an actual parameter, but overall concise and well-structured.

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?

Output schema exists and is rich (5 params, all documented). The description covers what's expected of a filtered list tool. The one gap: 'freshness' is referenced in the description but no freshness parameter exists, which could confuse the agent about what filtering is actually available.

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

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

Schema description coverage is 100%, so all 5 parameters are described in the schema itself. The description adds 'freshness' as a filter axis (not a parameter, suggesting time-based filtering exists implicitly), and 'project_workspace reports them' for kind/status is useful cross-tool pointer that goes slightly beyond schema. 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?

Description is clear: 'List indexed and managed documents, filtered by kind, status or freshness.' It identifies verb (list), resource (documents), and the three filter axes. It distinguishes from siblings by noting these are 'indexed and managed' documents (vs card/changelog/memory lists), though it doesn't explicitly name an alternative sibling for filtering.

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

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

The description implies a query/filter tool and mentions 'indexed and managed' distinction which hints at scope, but it doesn't explicitly state when to use this vs project_doc_create/patch/move or when the managed vs indexed distinction matters practically. The managed parameter hints at one usage nuance but no explicit when-to-use guidance is given.

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 and destructiveHint=false, and the description competently adds context: the DOC ID is stable across moves, and an empty folder targets the root. The expectedRevision optimistic-concurrency detail is valuable. No contradiction with the idempotentHint=true annotation; moving a doc to a location is plausibly idempotent.

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

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

Two focused sentences with zero waste. The first states the action and constraint; the second adds the critical ID-stability fact and root-folder convention. Every word earns its place.

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

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

The tool is simple with a strong schema (100% coverage) and an output schema present. The description covers the key behavioral nuance (ID stability, root targeting) plus concurrency semantics via expectedRevision in the schema. Adequately complete for this level of complexity.

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 parameter descriptions are strong (id, folder with root semantics, expectedRevision with concurrency behavior). The description adds the 'DOC ID never changes' fact and root convention, which complements rather than duplicates the schema. Baseline 3 is appropriate since the schema already carries the load.

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

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

The description states 'Move a managed document to another folder below the managed docs root' — a specific verb (move), resource (managed document), and destination (folder below root). It distinguishes from sibling doc tools (create/list/patch) by focusing on relocation. However, it doesn't explicitly name alternative tools for other doc operations.

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

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

The description implies when to use it (moving a document) but doesn't state when not to use it or name alternatives like project_doc_patch or project_doc_create. The 'DOC ID never changes' note and root-folder convention provide some usage context, but there's no explicit 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?

With idempotentHint=true annotation present, the bar is lower. The description adds genuine value by explaining the optimistic concurrency behavior (write refused on revision mismatch, concurrent edits reported rather than overwritten) and the read-only constraint on indexed repo docs. It doesn't mention the return format or error behavior in detail despite having an output schema, but the annotation plus inline concurrency explanation provide solid coverage.

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

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

Two compact sentences that are front-loaded with the primary purpose and mechanism. The second sentence adds a critical safety constraint (read-only indexed docs) without padding. No filler or redundant restatement of the title. Slightly more guidance on return shape could push it higher, but overall it's economical and earns its sentences.

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

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

The tool has nested objects and an output schema, so the description doesn't need to explain return values. The description covers the concurrency mechanism, the partial-update behavior, the read-only restriction, and references the move tool for folder changes. This is well-rounded for a patch tool of moderate complexity, though it could mention error responses (e.g., revision conflict handling details) beyond what the schema states.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond schema: it notes indexed docs are read-only, and it states that only keys present in 'changes' are touched (partial update semantics). The expectedRevision parameter's concurrency behavior is already well-described in the schema itself, so the description's mention reinforces rather than duplicates it. The partial-touch semantics in the description meaningfully complement 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 'Patch a managed document using optimistic concurrency' — a specific verb+resource with a distinctive mechanism (optimistic concurrency). It also adds important scoping information by noting indexed repository docs are intentionally read-only through this tool. While the sibling project_doc_move is separately named for folder changes, the description doesn't explicitly differentiate from other patch tools like project_card_patch or project_memory_patch, though those target different resource types so the distinction is reasonably clear.

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

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

It states when to use (patch managed docs) and explicitly excludes indexed repository docs ('edit those files directly'), providing a clear when-not. The exclusion is valuable context. However, it doesn't contrast with the sibling patch tools (card, memory, changelog) explicitly, leaving the agent to infer resource-type differentiation, nor does it mention the project_doc_create/list alternatives for creation/listing flows.

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 provides solid behavioral context: it validates multiple artifact categories and checks cross-record references, and critically mentions that checkPaths performs a filesystem walk which can be disabled on large repos (a cost/perf disclosure). Annotations already declare readOnlyHint=true and destructiveHint=false, which the description aligns with. The description adds the performance-aware behavior about the filesystem walk beyond what annotations 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?

The description is a single, information-dense sentence followed by a directive clause. Every word earns its place: it enumerates the validation targets, mentions cross-record references, and states the trigger condition. No filler, no redundancy with the schema 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?

The description is complete enough for this tool's complexity: single optional parameter fully documented in schema, output schema present (so return value details are covered elsewhere), and annotations declare the read-only, idempotent, non-destructive safety profile. The validation scope is enumerated explicitly. A pre-completion diagnostic tool with good schema/annotation coverage doesn't require much more.

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 checkPaths is fully documented in the schema itself (verify paths exist, skip filesystem walk on large repos). The description complements the schema by mentioning the filesystem walk implication ('checkPaths' behavior) in the context of validation scope. Since there's only one well-documented param and schema coverage is complete, the description doesn't need to add much here.

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

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

The title and description clearly state the verb+resource: 'Run workfile doctor' and 'Validate Work, Docs, History, Memory, agent instructions, CI templates and cross-record references.' It enumerates the specific things validated, distinguishing it from sibling tools like project_card_list or project_memory_list, which are individual-file operations. The 'Run before declaring work finished' clause gives the purpose strong operational context.

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

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

The description provides clear when-to-use guidance ('Run before declaring work finished'), establishing it as a pre-completion verification step. It doesn't explicitly name alternatives or exclusions, but given the tool's unique validation role among siblings (none of which do cross-record validation), direction is reasonably clear. A named alternative or 'when not to use' would push this to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, fully covering the safety profile. The description adds value by specifying the exact return contents (body, revision, outgoing references, backlinks, health signals) and the critical revision behavior — that the returned revision is what a later write passes as expectedRevision. This is genuinely useful beyond annotations, though it doesn't describe error cases (e.g., 404 for nonexistent IDs) 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 efficient sentences, zero filler. The first states the action and scope; the second provides a critical behavioral detail about revision semantics. Every word earns its place.

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

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

With a rich output schema, good annotations, and a single well-documented parameter, the description is nearly complete. The revision→expectedRevision linkage is a subtle and important behavior clearly disclosed. It could mention error handling for nonexistent IDs, but given the completeness of structured fields, this is a minor 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% — the id parameter is fully documented with examples (T-0042, DOC-0003, etc.) and a clear definition of stable record ID. The description adds the key semantic detail that the revision value is reused by writes as expectedRevision, which is valuable context linking this read to the write flow. Baseline of 3 is appropriate since the schema already handles parameter documentation well.

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?

Clear verb+resource: 'Read one canonical project record by stable ID'. It specifies exactly what's returned (body, revision, outgoing references, backlinks, health signals). Distinguishes from siblings like project_doc_list and project_search which fetch multiple/filtered results. The scope ('one canonical record') is unambiguous.

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

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

The description states it reads by stable ID and notes this is the getter counterpart to write tools. It implies this is for fetching single records by ID rather than listing/searching. However, it doesn't explicitly name alternative tools or state when NOT to use it (e.g., for bulk retrieval use project_search/project_card_list).

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, so mutation is implied by the annotation already. The description adds the intended-use context (behavior-changing knowledge vs session narration). However, it doesn't disclose what happens on record creation (return value, whether duplicates are checked, side effects like index updates, or how errors are surfaced). With 4 annotation fields all set to defaults/false, the description doesn't compensate for the lack of behavioral detail.

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 two sentences and front-loads the purpose immediately in sentence one. Sentence two provides the essential exclusion criterion. It's efficient with no filler. Slightly more guidance on when NOT to use (which alternative tool for narration) would push it to 5, but as written it earns its place.

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

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

For a 20-parameter tool, the description relies heavily on the schema (100% coverage) and output schema being present to explain return values. The description correctly focuses on the selection decision (which collection type, purpose vs narration). The phrase about status vocabulary varying by collection and being project-declared is valuable cross-tool guidance referencing project_workspace. The main gap is no explicit statement about whether related records or supersede chains are validated/created atomically.

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 description need not repeat parameter meaning. However, the description adds meaningful cross-collection guidance, particularly the collection enum values ('learnings: something discovered... decisions: a choice made... incidents: something that broke...') in the schema itself, and pointers like 'prefer project_memory_supersede' for supersedes, and 'project_workspace reports them' for status. This enriches param semantics beyond bare types.

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

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

The description clearly states the verb (Create) and resource (typed learning, decision, incident, convention or temporary context record). It distinguishes from sibling tools (project_memory_list, project_memory_patch, project_memory_supersede, project_memory_graduate) by being the add operation. The phrase 'not for narrating what happened this session' adds a clear exclusion criterion.

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

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

The description explicitly states the tool is for 'knowledge that should change future behaviour' and excludes 'narrating what happened this session'. While it doesn't name specific alternative tools for the 'narrating' case, the collection parameter enum and cross-references to project_memory_supersede and project_memory_graduate in schema properties provide contextual alternatives. It could more explicitly say which sibling handles narration.

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, so it's clearly a write operation. The description adds the key dependency constraint (target must pre-exist) and the expectedRevision param is documented in the schema. Since annotations already establish the mutation context and the schema covers revision guarding, the description adds meaningful context with the prerequisite rule.

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 two tight sentences with zero filler. It front-loads the action and adds the critical prerequisite in the second sentence. Only minor credit lost for not structuring the prerequisite as an explicit 'When to use' framing.

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 full schema coverage, an output schema present, and annotations clarifying it's a non-readonly write, the description covers the core workflow (create target first, then graduate). The completeness is strong given what structured fields already provide, though it doesn't describe what happens to the learning's state beyond 'graduated'.

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 all three parameters (id, targets, expectedRevision) are documented in the input schema. The description adds context about targets being conventions/decisions/documents and the expectedRevision referential integrity behavior, but the schema already explains these thoroughly. Baseline 3 for full schema coverage 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?

The description states a specific verb+resource (graduate a learning/mark as graduated and link it to the target record). It clearly distinguishes from siblings like project_memory_supersede (which likely supersedes a learning differently) and project_memory_patch. The 'mark as graduated and link to durable rule' phrasing is specific.

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

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

The description gives clear guidance to create the target record first ('graduating points at something that must already exist'), which is a critical prerequisite. However, it doesn't explicitly contrast with alternatives like project_memory_supersede or state when to graduate vs supersede, which would push to 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the scoping dimension (filter by collection or lifecycle status) and notes that status vocabularies are project-declared and vary by collection, which is genuinely useful behavioral context beyond the schema. This adds good value atop strong 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?

A single tight sentence that captures purpose and filtering dimensions with zero filler. Every word earns its place, and the collection\.enum in the schema carries the detailed vocabulary without cluttering the description.

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

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

For a read-only list tool with 100% parameter coverage, an output schema present, and strong annotations, the description is quite complete. The one gap is guidance on how it relates to project_search/project_get_record for discovering memory content, but this is minor given the structured annotations and schema richness.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (limit, offset, status, collection). The description lists what the tool filters by but doesn't add much beyond what the schema provides — the collection enum is fully specified in-schema, and the status field already explains its variability. At full coverage, the baseline of 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?

The description states a specific verb+resource ('List durable memory') and enumerates the content types (learnings, decisions, incidents, conventions, context) plus the filtering dimensions (collection, lifecycle status). It's clear, though it doesn't explicitly distinguish itself from sibling tools like project_card_list or project_changelog_list — the memory vs card distinction is implied by the title and description.

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

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

The description implies this is a read/list operation for durable memory records and mentions filtering options. However, it doesn't explicitly say when NOT to use this (e.g., vs project_search for cross-cutting queries or project_card_list for card-type records). The breadth of sibling tools makes this guidance gap noticeable, but the readOnlyHint and list-focused purpose provide reasonable implied context.

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 explains the optimistic concurrency mechanism (write refused if expectedRevision no longer matches, concurrent edit reported rather than overwritten), which adds meaningful behavioral context beyond the annotations. While annotations declare idempotentHint=true and readOnlyHint=false, the description's explanation of the revision-refusal behavior adds genuine value. It could note the destructive nature of body replacement more explicitly, but the 'only keys present are touched' qualifier helps.

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

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

Two sentences, zero waste. The first sentence states the core action with the concurrency qualifier, and the second gives a precise pointer to an alternative. Every word earns its place.

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

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

For a memory-record patching tool with 100% schema description coverage, a rich output schema, and detailed per-parameter documentation, the description is complete. It covers the action, the concurrency behavior, the partial-update semantics (delegated to schema), and the sibling distinction. The schema already explains expectedRevision and changes thoroughly, and the description adds the retire-orientation.

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 each parameter already has detailed descriptions in the schema, including the revision string's purpose, the id prefix pattern, and the changes semantics with partial-update behavior. The description's main contribution is naming the retire flow via supersede, which reinforces schema content but doesn't add substantial new parameter semantics beyond what's 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?

The description clearly states the tool patches a durable memory record using optimistic concurrency, with a specific verb (patch) and resource (durable memory record). It explicitly distinguishes itself from the sibling project_memory_supersede, naming the alternative and explaining the difference (retirement updates both sides).

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

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

The description explicitly says when NOT to use this tool: for retiring a record in favour of another, pointing to project_memory_supersede as the alternative. This is direct when/when-not guidance with a named sibling tool, exactly the highest tier of usage 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 declare readOnlyHint=false and destructiveHint=false, which already convey this is a write operation that isn't destructive. The description adds atomicity ('update both sides atomically') and the non-deletion detail, which is genuinely useful. However, it doesn't disclose behaviors like whether the operation requires additional permissions, whether it's reversible, or what the response shape validates—though the output schema partially covers the latter.

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, no filler. Every clause adds value: atomicity, prerequisite ordering, non-deletion behavior, and ID persistence. Front-loaded purpose with critical behavioral caveats following. 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 3-parameter tool with full schema coverage and an output schema present, the description covers the core semantics well: atomicity, prerequisite, and non-destructive nature. It could mention reversibility or permission requirements for full completeness, but for the complexity level this is solidly complete.

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

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

Schema description coverage is 100%, so all three parameters already have descriptions in the schema. The description reinforces that replacementId 'must already exist' and explains the expectedRevision 'revision string' guard (concurrent edit protection), which adds semantic meaning beyond the schema. With full schema coverage, this is the appropriate baseline 3 with slight credit.

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 ('supersede') and resource (memory records), and clearly explains the binary relationship: one record supersedes another with both sides updated. It distinguishes itself from siblings like project_memory_graduate and project_memory_patch by framing the action as a pair-wise replacement rather than a single-record modification.

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

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

The description explicitly instructs to 'Create the replacement first' as a prerequisite, and explains the important exclusion: 'neither record is deleted, so the superseded one stays readable and its ID keeps resolving.' This gives clear when-to-use framing and sets expectations about alternative behaviors (non-destructive) that differentiate it from delete-like operations.

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, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds behavioral value by defining what 'actionable' means (unblocked, unclaimed or claimed by you) and the ranking logic (highest priority first), which are non-obvious behaviors not in annotations.

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

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

Two sentences, zero waste. The purpose statement and the guiding question are both front-loaded and directly actionable. Every word earns its place.

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

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

For a read-only ranking tool with an output schema present, full parameter schema coverage, and comprehensive annotations (readOnly, idempotent, non-destructive), the description is complete. It explains what it ranks, the filtering rules, and the ordering logic. No gaps that would confuse an agent.

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

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

Schema coverage is 100%, so baseline is 3. The area parameter description is useful ('Project-declared, so the accepted values vary; project_workspace reports them'), which adds meaning beyond the schema. The actor and limit parameters are adequately described in the schema and the description doesn't need to repeat them.

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?

Specific verb+resource: 'Rank actionable cards' with clear scope (unblocked, unclaimed or claimed by you, highest priority first). The description directly answers the question 'what should I do now', distinguishing it from card_list (listing), card_create (creating), etc. Clearly distinct from 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?

The description states it ranks actionable cards with defined inclusion criteria and explicitly frames it as an answer to 'what should I do now'. While it doesn't explicitly name alternative tools to use instead, the purpose framing plus sibling context (card_list, search) makes the usage situation clear. Could add exclusions for alternatives but the core context is present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds behavioral context about deterministic lexical ranking and the optional semantic provider fallback behavior, which is genuinely useful. However, it doesn't describe token cost implications between modes beyond what the schema's 'view' parameter already hints at; the description doesn't independently disclose behavioral traits like pagination or result ordering beyond ranking mention.

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 well-formed sentences with zero wasted words. The first sentence states the scope precisely, the second explains the ranking mechanism. Every element contributes value.

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?

Description plus a comprehensive 100%-covered schema and rich annotations together fully specify the tool, including its hybrid/lexical modes, view choices, and record-family filtering. An output schema exists so return format doesn't need explaining. The only minor gap is that the description could hint at the breadth of use cases served by a cross-family search vs individual list tools like project_card_list.

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 all 5 parameters (mode, view, kinds, limit, query) are documented in the input schema itself. The description adds the deterministic-vs-semantic behavioral distinction for the 'mode' parameter, which complements the schema. However, it doesn't add further semantic guidance beyond what the schema already covers, so the 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?

The description clearly states it searches multiple record types (cards, documentation, changelog, releases, durable memory) with a specific verb 'Search' plus resource. It distinguishes from siblings like project_card_list and project_doc_list by covering all record families, though it doesn't explicitly name an alternative for differentiated queries.

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

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

The description notes it 'Uses deterministic lexical ranking and an injected semantic provider when available,' giving context on how search behaves. It implicitly covers when to use (broad cross-family search) vs more specific list tools, but doesn't explicitly state when not to use it or name alternatives.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by listing the specific categories of info it reports (areas, axes, document kinds, changelog types, memory collections) and the 'effective' workspace qualifier. No specific output/pagination details, but the output schema exists to cover that.

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 concise sentences. The first states the purpose precisely, the second gives actionable usage guidance. No wasted words — every sentence earns its place.

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

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

A parameterless read tool with strong annotations (readOnly, idempotent, non-destructive) and an output schema. The description adds the crucial 'read this first' sequencing guidance and enumerates the domain categories it covers. Complete for this tool's complexity.

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 has zero parameters, so the schema fully documents the input surface (100% coverage, empty properties object). With no params, the baseline is 4 — and the description correctly focuses on what the tool RETURNS rather than inputs, which is appropriate here.

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

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

The description states it returns 'the effective Workfile workspace, schema, enabled modules and mutation mode' — a specific verb+resource combination. It doesn't explicitly distinguish from siblings, but 'read this first' hints at its foundational role among the many project_* 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?

It explicitly says 'Read this first when a vocabulary is project-declared' and enumerates what it reports (areas, axes, document kinds, changelog types, memory collections). It provides clear context for when to invoke it, though it doesn't name specific alternative tools to exclude.

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