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

Annotations only indicate that the operation is not read-only and not destructive. The description adds valuable behavioral context: activating a change tags journal entries from mutating operations and makes the change the default for change tools. It also mentions the return value, going beyond the annotations.

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

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

Three short sentences deliver purpose, side effects, and return value with no filler. The key action is front-loaded and 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 description is sufficient for a simple two-parameter tool: it explains the operation, its consequences, and the return value. It does not elaborate on error cases or the fate of a previously active change, but those are not essential for invoking the tool correctly.

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

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

Schema description coverage is 100%, with both changeId and workspace clearly documented. The description does not add parameter-level details beyond the schema, so the baseline of 3 applies.

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

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

The description begins with a specific verb and resource: 'Make an existing change the active one.' It clearly distinguishes this from sibling tools like change_create (creation) and change_status (status reporting) by focusing on setting the active/default change, and it adds concrete behavioral effects.

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 for when to use the tool: when an existing change should become the active context for journal tagging and for change tools' default behavior. It does not explicitly name alternatives or exclusion conditions, so it stops short of full when/when-not guidance.

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

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

Annotations only indicate readOnly=false, openWorld=false, destructive=false. The description adds substantial behavioral detail: making the new change active, creating a JSON record plus a stage-document directory, writing documents on demand, and deriving a deduplicated kebab-case id. This gives the agent a concrete model of side effects beyond what annotations provide.

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

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

Front-loaded with the core action in the first sentence; each following sentence adds a distinct fact (concept, use case, id rule, workflow next steps). It is slightly longer than the bare minimum, 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 description covers creation semantics, id generation, and the surrounding workflow. However, with no output schema, it does not say what the call returns (e.g., the generated id or change object), and it leaves the effect on any previously active change implicit.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that the title becomes the kebab-case id with -2, -3 collision deduplication, which directly affects how an agent should choose a title.

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

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

States a specific verb and resource: 'Create a tracked change ... and make it the active change.' This clearly distinguishes creation from sibling change_activate and positions the tool within the change lifecycle, so an agent can tell it apart without opening the schema.

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

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

Clearly identifies the intended use ('track multi-step work so any future chat can re-orient with a single change_status call') and gives explicit next steps with change_doc and task_add. It does not explicitly say when not to use it or name alternatives for existing changes, so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses the default replace behavior, the append option, the exact file path pattern, and the return value (workspace-relative path and existing stage documents). This adds meaningful behavioral context that annotations do not provide, such as the overwrite semantics and the location convention. It does not contradict any annotation.

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 three sentences with no filler. The first sentence states the core purpose, the second explains the append/replace behavior, and the third gives the location and return value. Each sentence earns its place and information is front-loaded.

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

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

Given the tool's moderate complexity (5 params, no output schema) and available annotations, the description covers the key operational details: purpose, overwrite semantics, file path, and return value. It does not explicitly mention the active change default or the clean error for unknown changeId, but those are documented in the input schema, so the description is adequately complete for an agent to invoke the tool correctly.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by showing how parameters map to the file path (<workspace>/.workspace-mcp/changes/<id>/<stage>.md) and reinforcing the append behavior. This goes beyond the schema's per-property descriptions by illustrating the relationships between workspace, changeId, and stage.

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

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

The description opens with a specific verb and resource: 'Write one stage document of a change: proposal, spec, design or notes.' It names the four stage types and clarifies this is for change documents, distinguishing it from generic file tools like write_file or edit_file. The first sentence alone fully conveys the tool's unique purpose.

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 for when to use the tool: it writes change stage documents, can be written in any order, and on demand. It explains the replace/append options but does not explicitly name alternative tools or state when not to use it. The purpose is narrow enough that usage is clear, but explicit sibling differentiation 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, and the description reinforces this with 'Never writes state and is never journaled,' adding the journaling detail beyond the annotations. It also discloses fallback behavior ('with no active change'), the full list of rendered content, and the meaning of all: true. No contradiction with annotations 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?

The description is dense but well structured: it front-loads the read-only orientation purpose, then details the two modes and the safety guarantee. It is slightly longer than strictly necessary because the final 'Never writes state' partially repeats the opening 'Read-only' framing, but every sentence otherwise adds useful information.

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

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

For a tool with three optional parameters and no output schema, the description thoroughly covers invocation modes, output contents, default behavior, fallback when no active change exists, and side-effect guarantees. An agent has everything needed to call it correctly without inferring missing behavior.

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 three parameters. The description adds behavioral nuance around all: true and the no-argument default, but it does not substantially extend the meaning of changeId or workspace beyond what the schema states. This matches the baseline for fully self-documenting schemas.

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

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

The description names a specific verb and resource: a read-only orientation call that renders the active change in full or lists all changes. It clearly distinguishes itself from sibling mutation tools like change_create and task_add by emphasizing it never writes state. The phrase 'the single way to re-orient on tracked work' makes its role 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 gives explicit usage context: use it at the start of any chat to re-orient on tracked work. It also explains the two call modes (no arguments vs all: true) and the no-active-change fallback. It does not name sibling alternatives explicitly, but the read-only framing plus sibling names like change_create and task_add make the boundary clear enough.

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 indicate this is a mutating operation (readOnlyHint=false), and the description confirms and elaborates by saying the tool appends rather than replaces. It adds meaningful behavior beyond annotations: constraints persist and are surfaced by change_status in later chats. No contradiction with annotations was found.

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 with no filler; the core action and an illustrative example are front-loaded, and the persistence rationale is stated in one concise second sentence. Every part adds 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 a small append-only tool, the description plus fully documented schema covers how to use it, what the constraint is for, and how it will be visible afterward. With no output schema, it does not describe the return value, but that is low-stakes for this operation and does not impede correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the text parameter's intended form with an example and explains persistence, but it does not add new details about changeId or workspace beyond what the schema already provides. The example is helpful but not essential given the schema already says 'phrased as a short rule.'

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 pair, 'Append one constraint to a change,' and clarifies what a constraint is with an example ('no new runtime dependencies'). It clearly distinguishes this from siblings like task_add and change_doc by focusing on constraint semantics and their persistence through change_status.

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 for when to use the tool: when the work needs a rule, limit, or requirement to be remembered and respected. It also explains why this tool is useful rather than just re-asking later. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to infer appropriate use.

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

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

Annotations already declare destructiveHint=true, but the description adds meaningful context: 'The change is written to disk immediately and is not reversible.' This goes beyond the structured hint by disclosing immediacy and irreversibility, which materially affect how an agent should invoke the 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?

Four sentences, each earning its place: purpose, matching constraint, ambiguity handling, and atomicity guidance via patch. The core behavior is front-loaded and no words are wasted.

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

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

For a destructive mutation tool, the description covers the prerequisite (read_file first), the matching pitfalls, the multi-occurrence handling, and the reversible-vs-atomic tradeoff with an alternative tool. No output schema exists, but return values are secondary for a tool whose effects are the point; the description is complete enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains that oldString must match the file content exactly including whitespace and indentation, explains the ambiguity condition ('If oldString appears more than once'), and prescribes the remedy (more context or replaceAll=true). These semantics are not present in the schema.

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

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

The description states a specific verb and resource ('Replace an exact string in an existing text file'), and the exact-match semantics distinguish it from siblings like write_file and patch. An agent can immediately tell what this tool does and how it differs from nearby alternatives.

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 instructs the agent to read the file first with read_file and names patch as the preferred alternative when multiple changes must be atomic ('so all edits succeed or none are applied'). This gives clear when-to-use and when-not-to-use guidance without leaving it to inference.

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

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

Discloses execution details (LC_ALL=C, 30 s timeout, no shell), return shape (patch text, '(no changes)' on empty), and truncation behavior at 64 KiB. These add real behavioral context beyond the readOnlyHint/openWorldHint annotations; no contradiction.

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

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

Four sentences with no filler; the core purpose is front-loaded, and implementation details and edge cases are compactly packed. Every sentence carries operational information.

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

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

For a read-only tool with full schema parameter documentation, the description is complete: it covers command execution, output format, empty-diff behavior, output size handling, and the workspace parameter. Since no output schema exists, the explicit return explanation is valuable.

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 met and schema descriptions already document each parameter. The description adds flag-level mapping (staged=true for --cached, stat=true for --stat, path passed after '--'), which helps agents use parameters correctly.

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

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

States 'Read-only git diff of the workspace' — a specific verb, resource, and scope, and clarifies it runs without a shell, distinguishing it from mutating or shell-based siblings. It could go further by explicitly naming alternatives like git_status or patch, so it stops short of full sibling 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?

Provides clear context for when to use the tool (any need for a git diff of the workspace) and covers the main option flags (staged, stat, path), but it does not explicitly contrast it with sibling tools. The guidance is adequate but largely implied rather than stated as selection criteria.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing the exact command, environment settings (LC_ALL=C), timeout (10 s), output format ('branch: ...' header plus porcelain lines), clean-tree behavior, and error handling for non-repository directories or missing git binaries. This is rich behavioral context that helps an agent anticipate results and failure modes.

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 information-dense but every sentence contributes: command specification, environment and timeout, output format, clean-tree behavior, error handling, and a usage note. Key details are front-loaded with 'Read-only git status' and the command, followed by supporting behavior details. No filler is present.

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 tool with one optional parameter and no output schema, the description covers everything an agent needs: input, command behavior, output format, edge cases, and error reporting. There are no significant gaps in context for correct invocation and interpretation.

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 single parameter 'workspace' is fully described in the input schema, including its default behavior, so schema coverage is 100%. The tool description itself does not need to add parameter semantics. Baseline 3 is appropriate because the schema already carries the necessary meaning.

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

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

The description states a specific verb ('git status'), the exact command form ('git status --porcelain=v1 -b'), and explicitly marks it as read-only, distinguishing it from mutation tools in the sibling list. It also clarifies what the tool does not do (no shell, no --shell flag). This makes the tool's identity 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 clearly establishes when to use the tool: to obtain the git status of a workspace. It also provides practical usage context such as not needing a --shell flag and how clean trees and error cases are reported. It does not explicitly contrast with siblings like git_diff, but the scoped purpose is strong 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=true, so the safe-read nature is covered without redundancy. The description adds genuinely useful behavior beyond annotations: it skips binary files and the .git, node_modules, and .cache directories, and it defines the exact match output shape. Minor gap: it does not spell out that matching is line-oriented rather than context/block based, though the output format implies it.

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

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

Four sentences, each earning its place: core purpose and output format, usage trigger, narrowing strategy, behavioral caveat, and exclusions. The most decision-relevant fact is front-loaded, and no sentence is redundant with the annotations or schema.

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

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

The definition is complete for a 6-parameter read-only search tool with no output schema. It covers what is searched, how matches are formatted, which directories are excluded, how to narrow the search, and which siblings to use instead. Parameter defaults live in the schema (maxResults cap, workspace default), and the read-only guarantee lives in the annotations.

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 already documented at the schema level; the baseline of 3 applies. The description adds only marginal strategic value by saying 'Narrow the search with path and include', which groups parameters into a usage pattern but does not add per-parameter detail beyond what the schema provides.

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

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

The description opens with a specific verb and resource ('Search file contents in the workspace') plus the mechanism (JavaScript regular expression) and an explicit output format ('relative/path:LINE: <line text>'). It clearly differentiates from siblings by stating this finds where a symbol, string, or pattern appears, and names list_files/read_file as the tools for adjacent tasks.

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 an explicit use case ('find where a symbol, string or pattern appears'), notes how to narrow results ('Narrow the search with path and include'), and names the two alternatives with the conditions that route to them ('Do not use it to list files (use list_files) or to read a known file (use read_file)'). An agent needs no inference to pick the right tool.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: it skips .git, node_modules, and .cache, does not follow symbolic links, and sorts by workspace-relative path. It does not detail the exact output format beyond the trailing slash marker, but that is a minor gap given the annotations.

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

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

The description is three sentences with zero waste. The core behavior and output format are front-loaded, followed by usage guidance and exclusions. 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 read-only listing tool with 100% schema coverage and no output schema, the description is nearly complete. It covers purpose, exclusions, symlink behavior, and routing to siblings. The only minor gap is that it doesn't describe the exact return structure beyond the trailing slash marker, but that is not essential for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds a little extra meaning by explaining the glob pattern semantics ('Patterns without a slash match the name at any depth') and the default/cap behavior, but most parameter meaning is already in the 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?

The description states a specific verb ('List'), a resource ('files and directories inside the workspace'), and a distinguishing behavior (sorted by workspace-relative path, directories marked with trailing '/'). It also explicitly contrasts with siblings read_file and grep, so an agent can tell it apart without opening schemas.

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

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

The description explicitly says when to use this tool ('to discover what exists before reading or editing') and when not to use it ('Do not use it to read content (use read_file) or to search text (use grep)'). It also mentions optional glob filtering, giving clear context for 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?

Goes well beyond the destructiveHint and readOnlyHint annotations: describes validation against current file contents, atomic all-or-nothing failure behavior with failing edit index reporting, and immediate disk writes when all edits are valid. This is exactly the kind of behavioral detail an agent needs.

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

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

Five sentences, each carrying distinct information: function, atomicity/failure behavior, usage guidance, prerequisite, and write timing. Front-loaded with the core capability and no filler.

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

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

The description covers what the tool does, when to use it, prerequisites, failure semantics, and persistence behavior. Given the moderate complexity, the complete schema coverage, and the existing annotations, nothing material is missing for an agent to invoke this correctly.

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

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

The schema already documents all parameters with 100% coverage, including exact-match semantics for oldString and replaceAll behavior. The description adds context about 'exact-string' edits and atomic validation, but does not add significant per-parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific action: apply several exact-string edits across files as one all-or-nothing operation. Clearly differentiates from sibling edit_file by naming it and explaining when patch should be preferred.

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 this instead of several edit_file calls when changes belong together' and instructs to read files first with read_file. This gives an agent clear selection criteria and prerequisites.

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

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

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds valuable behavioral context beyond that: UTF-8-only support, rejection of binary files, and the exact line-numbered output shape. It stops short of describing error behavior, but the disclosed traits are sufficient for a read operation.

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 with no wasted words. The purpose and output format are front-loaded, followed by compact usage guidance and exclusions. 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?

For a read-only file tool, the description covers what it reads, how output is formatted, when to use it, and which tools should be used instead. With no output schema present, the explicit line-number format is especially valuable and makes the tool effectively self-contained.

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

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

Schema description coverage is 100%, and every parameter already has a clear description. The description adds only light semantic color by mentioning offset/limit for line ranges, but it does not meaningfully extend what the schema already provides. This matches the baseline for high 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 names a specific verb ('Read'), a specific resource ('UTF-8 text file from the workspace'), and the output format ('1-based line numbers'). It also distinguishes itself from siblings by explicitly excluding search (grep) and discovery (list_files), so an agent can select it correctly without opening the schema.

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

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

The description gives concrete when-to-use guidance: before editing a file and for inspecting line ranges via offset/limit. It also gives explicit when-not-to-use guidance for binary files, content search (grep), and file discovery (list_files), naming the exact 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 mark the tool read-only and not open-world, and the description reinforces this. It adds behavioral context beyond annotations: notes are persistent, ordered newest-first, scoped to the workspace, and intended for recovering prior session context. This is useful but not exhaustive; it does not describe edge-case behavior such as empty results.

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 no filler. The main action and scope are front-loaded, followed by usage timing, filtering capability, and a clear pointer to the sibling alternative.

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 retrieval tool with four optional parameters, the description plus schema covers what the tool does, when to call it, how to filter, and which sibling to use instead. The absence of an output schema is not a serious gap here since the tool's purpose as a note reader is clear.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that query and tag filtering can be combined ('and/or tag') and clarifying that query is free-text, which is a useful semantic nuance beyond the individual schema descriptions.

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

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

States a specific verb and resource: 'Read the persistent notes saved with remember for this workspace, newest first.' It clearly differentiates from siblings like work_log and remember by naming them and defining the read/retrieval role.

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 tells when to use it: 'Call it at the start of a session together with work_log to recover context from previous chats.' It also identifies the alternative, work_log, for the automatic activity journal, giving the agent both positive and negative 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?

The description adds substantial behavioral detail beyond annotations: notes are 'append-only JSONL' stored under a specific path, and 'never edited or deleted by this tool'. This fully discloses persistence and mutation semantics, which is exactly the kind of context an agent needs.

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?

Every sentence earns its place: purpose, use-case timing, persistence model, and authoring guidance. The most important information is front-loaded, and there is no redundant filler.

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

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

For a simple create-note tool with rich annotations and full schema coverage, the description is complete: it explains why to call it, what to write, how data is stored, and how it will be retrieved later. Nothing essential for correct invocation is missing.

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

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

Schema coverage is already 100%, so the baseline is 3. The description adds meaningful usage semantics for text and tags ('short and self-contained', 'use tags for later filtering'), and clarifies the workspace-contextual nature of the note. It does not add detail about the workspace parameter, but the schema already covers that.

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 with a resource: 'Save a short persistent note for this workspace' and immediately ties it to recovery via 'recall', which distinguishes it from sibling tools like work_log or write_file. The purpose is unmistakable even before looking at the schema.

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

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

It gives clear context for when to use this tool: 'after finishing a chunk of work', and what to record (changes, next steps, decisions). It names recall as the recovery mechanism, but does not explicitly state when not to use it or how it differs from work_log, so it falls just short of a 5.

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

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

Annotations only convey that this is a non-read-only, closed-world, non-destructive operation. The description adds real behavioral facts annotations cannot express: task IDs are sequential (T1, T2, ...) and the task starts as pending unless another status is given.

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

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

Three short sentences each earn their place: the core action, the ID sequencing behavior, and the default status plus sibling routing. The main purpose is front-loaded and there is zero filler.

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

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

For a 4-parameter append tool whose schema documents every parameter, the description covers all distinctive behaviors an agent needs. The one gap: with no output schema present, it never states what the call returns (e.g., the newly assigned T-id), which the agent must infer from the sequential-ID note.

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

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

Schema description coverage is 100%, so all four parameters (text, status, changeId, workspace) already carry defaults, formats, and enum values. The description's "starts as pending unless another status is given" largely restates what the schema's "Defaults to pending" already says, adding little beyond it.

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

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

"Append one task to a change" names a specific verb, resource, and target scope, going well beyond the tautological title "Add task." It also differentiates from the most confusable sibling by noting task_update moves tasks between statuses.

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 final sentence gives an explicit when-not: "Use task_update to move a task between statuses," routing agents away from this tool for status transitions. Situating the operation "to a change" also orients it within the change lifecycle alongside siblings like change_create and change_activate.

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

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

The description goes well beyond the annotations by disclosing the all-or-nothing write behavior, pre-validation of every taskId, error behavior listing bad entries, optional note appending, and the single aggregate journal entry. This gives an agent a precise model of what will happen, including side effects.

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 compact: three sentences, each adding distinct value. The main purpose is front-loaded, followed by behavioral guarantees and side effects. No filler or redundant restatement of 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?

Given the annotations, full schema descriptions, and lack of an output schema, the description covers everything an agent needs to invoke the tool correctly: atomicity, validation, error shape, note behavior, and journal side effect. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents updates, changeId, and workspace. The description adds useful context around updates (atomic validation, error listing) but does not add per-parameter meaning beyond the 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?

The description opens with a specific verb and resource: 'Update the status of one or more tasks'. It makes the atomic all-or-nothing nature explicit, which clearly differentiates this from task_add and other task tools. The scope 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 clearly implies use when updating task statuses in bulk, which is evident from the opening sentenceabc and the schema. It does not explicitly name alternatives like task_add or state when not to use it, so it misses the highest bar, but the context is clear enough for correct 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=true, and the description reinforces this by listing which operations are journaled and stating read-only operations are never journaled. It adds useful behavioral context: entries are newest-first, carry change tags when a change is active, and can be scoped to one change. It does not detail pagination or exact outcome fields, but the annotations cover the safety profile.

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

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

The description is dense but well-organized: it front-loads the core purpose, then lists journaled operations, then gives usage guidance and filter hints. Every sentence earns its place, and the sibling distinction is included without padding.

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

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

For a read-only log tool with no output schema, the description covers what is logged, the ordering, the change-tag behavior, and when to use it. It does not describe the exact output shape or pagination behavior, but the limit parameter and the list of fields (timestamp, paths, detail, outcome) give an agent enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds a little context by mentioning filters (since, path, change) and explaining the change tag scoping, but it does not add substantial meaning beyond the schema's own parameter descriptions.

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

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

The description states a specific verb ('Read') and resource ('automatic activity journal'), enumerates exactly which operations are journaled, and distinguishes itself from recall by noting the log is automatic while recall reads deliberate notes. This clearly differentiates it from sibling tools like recall and change_status.

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 to call it at the start of a session to recover what happened in previous chats, and explicitly names recall as the alternative for deliberate notes. It also clarifies that read-only operations are never journaled, which helps an agent decide when not to use it.

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

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

Annotations already declare readOnlyHint, and the description reinforces it while adding substantial behavioral detail: it reports the primary workspace, presence of .workspace-mcp/ state, and active change id when state.json exists. This goes beyond annotation information.

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; the first front-loads the operation and return fields, the second gives the usage context. No filler or repetition of schema information.

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

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

For a zero-parameter read-only enumeration tool with no output schema, the description fully specifies the output fields and the important primary-workspace/default behavior. Nothing critical is missing for correct invocation and interpretation.

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

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

There are zero parameters, so the baseline is 4 and the schema leaves nothing undocumented. The description still adds useful context by noting that other tools default to the primary workspace and that this listing is the discovery mechanism.

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

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

States a specific read-only list operation with the resource ('named project workspaces served by this process') and enumerates the returned fields. It is unambiguous and clearly distinct from the file/state mutation 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?

Explicitly instructs the agent to call this tool first to discover workspace names and explains that every path or state tool accepts an optional workspace argument defaulting to primary. This gives direct when-to-use guidance for the surrounding toolset.

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

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

Beyond destructiveHint=true and readOnlyHint=false, the description reveals that parent directories are auto-created, writes are immediate, the whole file is replaced, and the operation is not reversible. These are behavioral facts an agent needs and would not know from annotations alone.

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

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

Three dense sentences, no filler, with the core action and key auto-directory behavior front-loaded, followed by usage routing and a caution about irreversibility. 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 3-parameter write tool with fully documented parameters and annotations, the description completes the picture: it covers side effects, timing, irreversibility, and sibling routing. No necessary information is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a new parameter-level behavior for path ('parent directories are created automatically') and emphasizes exact-content semantics for content, taking it just above baseline.

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

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

The description opens with a specific verb and resource ('Create a file ... or overwrite an existing file') and explicitly scopes it to 'new files or full rewrites.' It names edit_file and patch as distinct alternatives, so an agent can immediately tell this tool apart 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?

It gives explicit when-to-use ('new files or full rewrites') and when-not-to-use ('Prefer edit_file or patch for targeted changes'), with the reason being that this tool replaces the whole file. This is textbook usage routing.

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