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

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds that results are 'net, checked against disk' and include changes 'outside PerMark', hinting at deduplication and cross-boundary tracking, but it does not explain return format, pagination, or the precise meaning of 'net'. With annotations reducing the burden, this is a moderate addition.

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, front-loaded sentence with no wasted words. However, its extreme terseness introduces jargon like 'net' and 'hand-off' that may not be self-evident, trading clarity for brevity.

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

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

No output schema exists, so the description must carry the full burden of explaining what the tool returns. It does not describe the response structure, how rows are formatted, or what the different 'by' modes return, leaving significant gaps for a tool with three parameters and multiple modes.

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

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

Schema coverage is 67%: 'limit' and 'since' have clear descriptions, but the 'by' enum values 'person' and 'outside' are not explained in the schema or description. The description provides no additional parameter context beyond what the schema already states.

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

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

The description conveys that the tool reports a person's activity since a hand-off and changes outside PerMark, giving a specific resource and scope. However, it lacks a clear action verb and does not explicitly differentiate itself from siblings like get_context or list_unread, leaving the agent to infer when 'activity' is the right call.

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

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

There is no guidance on when to use this tool versus alternatives such as get_context, list_unread, or map. The description does not state prerequisites or scenarios where activity is preferable to searching or listing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description's real contribution is enumerating what is returned (document, mode, section, selection, unsaved, open comments), which effectively substitutes for the absent output schema. It stops short of saying what happens when nothing is open or how facets are structured.

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 clause listing the state facets with zero filler. The scope marker 'now' is front-loaded, so the key semantic (current, live state) lands immediately.

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

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

With no parameters and annotations covering read-only safety, the only gap was the return contract, and the description fills that by listing the state facets. It is nearly complete; minor omissions are the shape of each facet (e.g. whether 'open comments' is a list) and the empty-state 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?

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter behavior an agent could get wrong.

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

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

The description names a specific resource (the user's current position/state in PerMark) and even enumerates the facets: document, mode, section, selection, unsaved, open comments. That is far more than a tautology of 'get_context'. It does not, however, differentiate itself from siblings like 'read_note' or 'outline', so the agent must infer the boundary.

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 'Where the person is in PerMark now' implies a live-state lookup, so the use case is inferable. But there is no explicit when-to-use, no when-not-to-use, and no mention of alternatives such as 'read_note' or 'outline' for reading content rather than position.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context by listing the returned fields and the default 'open' filter, but says nothing about pagination, ordering, or volume.

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

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

A single compact sentence with the field list up front and the default stated at the end; every element is informative. Slightly telegraphic but not padded.

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

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

For a simple read-only list tool with no output schema, listing the returned fields is valuable and the default filter is stated. Only the relationship to resolve_comment is left unaddressed.

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

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

Schema coverage is 0% for the single `which` enum (open/done/all). The description partially compensates by stating 'open by default', clarifying the default value, but it does not explain what 'done' or 'all' select semantically.

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 ('comments on passages') and enumerates the returned fields (id, place, state, quote, text, heading, reply), so an agent knows exactly what it gets. It does not distinguish itself from the related sibling resolve_comment, which is the main clarity gap.

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 'open by default' hints at the default filtering behavior, giving implied usage context. However, it never states when to use this versus resolve_comment or list_notes, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds that results carry note, age, and title fields, but says nothing about ordering, completeness, or whether all shared notes are returned at once.

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 short sentence with no waste, and the scope qualifier plus returned fields arrive immediately. The fragment phrasing ('Notes the person shared with agents') is slightly awkward but costs nothing in 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?

With no output schema and no parameters, the description does the minimum by naming the returned fields (note, age, title). It leaves open whether results are paginated, ordered, or truncated, and 'age' is undefined, which matters for a zero-argument 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?

The tool takes zero parameters, so the schema requires no compensation; baseline is 4. The description does not need to explain any argument, and the parenthetical field list is a bonus rather than a substitute for parameter documentation.

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 phrase 'Notes the person shared with agents' identifies the resource and a scoping qualifier (shared with agents) plus the returned fields (note, age, title), so an agent can tell it is a listing tool distinct from list_unread or list_tags. However, 'Notes' is not a clear verb and there is no explicit statement of what the tool does versus read_note or search.

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 no when-to-use guidance, no exclusions, and never names alternatives such as list_unread, search, or read_note despite six list/read siblings in the toolset. The only implied usage is 'person shared with agents,' which is scope, not a selection rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral value that annotations cannot: the response includes document counts, and per-document path, tags, and description — valuable since no output schema exists. It omits ordering, pagination, and what happens for an unknown tag.

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 semicolon-joined sentence with zero filler, and the default (tag-listing) mode is front-loaded before the variant. Nothing is padded.

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

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

For a two-parameter read tool with no output schema, the description covers both modes and the key returned fields, which is reasonable. It still leaves gaps an agent would want: result ordering, whether `limit` applies per mode, and behavior when the tag does not exist.

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 both parameters and a baseline of 3 applies. The description clarifies that `tag` switches the tool into document-listing mode, but adds nothing about `limit` and does not say whether the limit caps tags in the first mode or documents in the second.

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 the resource (tags) and states two concrete modes: tag listing with document counts, and document listing for a given tag with the fields returned. This is specific enough to act on, though it's phrased telegraphically rather than as a verb+resource statement and names no sibling for contrast.

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

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

The 'with tag / without tag' split implies which mode to pick, which is genuine usage guidance. However, it never says when to prefer this over siblings like search, map, or get_context for tag-based lookup, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior — results are scoped to what has changed since last read and ordered newest first — but says nothing about pagination beyond the limit, truncation, or what counts as 'changed'.

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

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

One short sentence with zero padding, and the most decision-relevant clause (changed since last read) is front-loaded ahead of the ordering detail.

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

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

For a one-parameter read tool with annotations and a documented schema, this is close to sufficient, but it leaves open who 'the person' is (current caller vs. a specific user) and whether results are capped or paginated. No output schema exists, so a brief note on result shape would help.

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 limit parameter is fully documented in the schema (1..200, default 50), so the schema does the work and baseline 3 applies. The description does not mention limit at all, adding nothing beyond structured data.

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

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

Names a specific resource (documents) and a precise filter (changed since the person last read them) plus ordering, so an agent can tell it apart from plain listing tools. It lacks an explicit verb (e.g., 'list') and never names a sibling it differs from, so it stops just short of a 5.

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

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

There is no statement of when to call this versus alternatives such as activity, read, or list_notes, and no exclusions or preconditions. The agent must infer the use case from the name and the one-line summary.

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 state readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior: folders beyond the depth are counted rather than expanded, and it names the returned fields. It does not explain pagination behavior or what the count looks like.

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

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

It is very short and front-loads the resource and returned fields. The telegraphic phrasing ('size_tok', 'folders past depth counted') is efficient but slightly cryptic.

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

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

For a three-parameter read-only mapping tool with full schema coverage and no output schema, the description gives enough to understand the basic result shape and depth-counting behavior. It remains thin on call semantics, pagination, and how the output is organized.

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 path, depth, and limit with defaults and ranges. The description adds only that traversal is below a folder and that depth affects whether folders are counted, but does not explain parameter interactions or formats beyond the schema.

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

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

It conveys that the tool enumerates files beneath a folder and returns metadata such as size_tok, flags, tags, and description, but the verb is implicit and the name 'map' is metaphorical. It does not clearly distinguish itself from siblings like outline or search beyond the vague 'Start here.'

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?

'Start here' gives a weak hint that this is an entry point, but there is no explicit guidance about when to use this versus outline, search, get_context, or read. No exclusions or alternatives are named.

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 specify that the tool is non-destructive, idempotent, and not read-only. The description adds meaningful behavioral context by disclosing that it may start PerMark and deliberately avoids taking focus.

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 definition is a single, front-loaded sentence with no wasted words. The key behavior—showing a document without taking focus—is stated immediately.

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?

All three parameters are documented in the schema, and the description covers the important non-obvious effects: auto-launching and not stealing focus. With no output schema, no return-value explanation is needed.

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 parameter meanings are already fully documented. The description only parenthetically mentions line or heading and adds no new syntax or semantics beyond the schema.

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

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

The description uses a specific verb, "Show," and identifies the resource as a document in PerMark, including line/heading positioning. It clearly conveys the UI-opening behavior, but does not explicitly distinguish the tool from the sibling `read` tool.

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

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

It gives useful conditions such as starting PerMark if closed and not taking focus, but does not state when to choose this over `read` or other document-access siblings. Usage is implied rather than explicitly guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the tool returns structural parts with lines and token size, but it does not describe the output format in detail (e.g., structured vs. markdown) or any limitations. With annotations carrying the safety burden, 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?

It is a single, front-loaded sentence with no filler. The term 'size_tok' is slightly cryptic but still efficient; every phrase contributes to the 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 read-only outline tool with no output schema, the description gives a minimal sketch of return values (headings, JSON keys, config parts, lines, size_tok). It omits details about output formatting and does not differentiate from sibling tools like `map`, leaving some ambiguity an agent might need to resolve by trial.

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

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

Schema coverage is 100%, and the schema fully documents both `path` and `links`. The description does not mention the `links` parameter at all, so it adds no meaning beyond the schema. Baseline 3 applies when the schema is complete.

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 resource (parts of a file) and names concrete output types (headings, JSON keys, config parts) with supplemental data (lines, size_tok). The phrase 'before reading it' implicitly distinguishes it from the sibling `read` tool, though it does not explicitly name 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?

The phrase 'before reading it' clearly signals when to use this tool: to get a structural overview prior to full content retrieval. No explicit exclusions or alternative tool names are given, keeping it at a strong 4 rather than 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 establish that this is a read-only, non-open-world operation, so the description does not need to restate safety. It adds useful scoping behavior for `at` and whole-file reads, but does not cover errors, missing parts, or return format beyond implying text.

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 definition is a single dense sentence fragment with no wasted wording. The most important scoping rule, no `at` means the whole file, is placed at the end where it is easy to retain.

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

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

For a simple two-parameter read tool with annotations and no output schema, the description supplies the critical `at` semantics and whole-file behavior. It is nearly complete, though it lacks failure behavior and sibling differentiation.

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 goes beyond the schema by explaining `at` syntax with heading paths, anchors, key paths, and line ranges. `path` is not expanded beyond the schema, keeping it from a 5.

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

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

The description makes clear that this returns text from a file, either a specific part or the whole file, which is more specific than the bare name `read`. It does not distinguish itself from siblings such as `read_note` or `open`, so it stops short of a 5.

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

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

It explains how `at` selects a part of a file and that omitting `at` reads the whole file, but it gives no guidance on when to use this tool instead of `read_note`, `open`, `search`, or other siblings. Usage is only implied by the resource 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 and openWorldHint=false, so safety is covered. The description still adds useful context beyond them: the return value is text content, and the scope is limited to shared notes, which explains why some notes may not be retrievable.

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 clause, front-loaded with the return value and followed by the identifier source. Nothing extraneous.

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

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

For a one-parameter read tool with annotations and no output schema, the description covers what is returned and how to obtain the argument. Only edge behavior (missing or unshared note) is left implicit, which is minor here.

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% with a single 'note' parameter, so baseline is 3. The description earns an increment by telling the agent where the identifier comes from (list_notes), which the schema's bare 'Note name.' does not.

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 the resource and scope precisely: the text of ONE SHARED note, addressed by name. The verb is elided ("Text of one shared note"), and it doesn't explicitly contrast with the generic `read` sibling, but the specificity of 'one shared note' makes its purpose distinguishable from list_notes and read.

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

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

Implies a workflow by saying the `note` value is "the name list_notes gives", which signals list_notes must be called first. It stops short of saying when to use this over `read` or `get_context`, or what to do when a note isn't shared.

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 it as a non-destructive, idempotent write; the description adds two traits not in the annotations — that the reply is read by a person (so the content is user-facing, not a log line) and that this is the sole mutation available in the toolset. It does not state reversibility or what happens to an already-resolved comment.

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, with the core action front-loaded and the scoping constraint immediately after. Nothing could be cut without losing information.

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

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

For a two-parameter idempotent mutation with annotations and no output schema, the description covers purpose, audience, and scope adequately. Minor gap: it doesn't say what the caller gets back or how the comment's state changes afterward.

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 already documents both parameters (id from list_comments, reply = what you did, short). The description only adds that the reply is read by a person, a marginal gain over 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?

Names a concrete verb and resource: "Mark one comment done, with a short reply." The second sentence ("The only change an agent can make") distinguishes it from the many read/list siblings without naming them explicitly.

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

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

"The only change an agent can make" gives clear context for when this tool is the right choice among twelve largely read-only siblings. It stops short of explicit exclusions, such as when a comment should not be resolved or how to pick among multiple comments.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavior beyond that: it discloses the result fields (path, line, size_tok, snippet, heading) and the important mode switch where tags without a query degrade into document listing. It doesn't mention ranking or pagination, which keeps it off a 5.

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

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

It is very short with no wasted words, but the clipped, fragment style ('Sections matching words ...; tags narrow; tags alone list documents') sacrifices readability for brevity. Semicolon-joined fragments front-load the key facts but read more like schema notes than a 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?

With no output schema, the description usefully names the return fields, and the four parameters are fully documented in the schema. However, it leaves unclear what a 'section' is relative to the toolset's document model, how results are ordered, and how budget interacts with result count — gaps an agent may hit on first use.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the tags parameter's narrowing effect and its standalone listing behavior, but adds nothing about budget or limit semantics (fewer hits, shorter snippets) beyond what the schema already states.

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

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

The description is telegraphic — 'Sections matching words' — with no explicit verb, but it does convey the resource (sections, not whole documents) and the returned fields (path, line, size_tok, snippet, heading). The dual-mode clause 'tags alone list documents' distinguishes it from a pure document lister, though it never names a sibling such as read or outline.

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?

'tags alone list documents' is the only usage signal: it tells the agent what happens with tags-only input, but not when to prefer this over read, outline, get_context, or list_notes. There are no exclusions, prerequisites, or alternatives named.

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