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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the operation is an upsert that silently creates a new tag entity when the name is unknown, which is a side effect an agent should know about.

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 front-loaded sentence that covers the action and the conditional side effect with 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?

With an output schema present and annotations covering safety, the description needs only the action and the upsert behavior, both of which it supplies. Missing only tangential detail such as whether the tag is applied to multiple items or permission requirements.

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

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

Schema description coverage is 100%, and the schema already explains case-insensitivity, tag reuse, and where to obtain item_id. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Tag an item') plus the upsert nuance ('creating the tag if it doesn't exist yet'), which separates it from RemoveTag/DeleteTag/RenameTag. It does not explicitly name a sibling, so it falls short of the 5 bar.

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?

No when-to-use guidance, no prerequisites, and no reference to alternatives such as RenameTag or RemoveTag. The agent can infer the purpose but gets no routing help from the description.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so 'can't be undone' largely restates structured data. The description does add genuine value by disclosing the cascade: the associated note is deleted as well, which is not captured by any annotation. It stays silent on invalid/missing ID behavior, but the bar is lower given full annotation coverage.

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

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

Two short sentences, front-loaded with the action and immediately followed by the irreversibility warning. 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?

An output schema exists, so return values need not be explained, and the one-parameter destructive operation is well covered for a simple tool. The only minor gap is the absence of any note on failure modes or confirmation requirements.

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

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

Schema description coverage is 100% and the single parameter already has an example ('ann_x7y2z') plus a discovery pointer to ListHighlights. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource+secondary effect: 'Permanently delete a highlight and its note.' An agent can distinguish this from siblings like DeleteItem, DeleteTag, or SetHighlightNote without opening a schema, since it names the exact object type and states the cascading note deletion.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named (e.g., whether to clear a note via SetHighlightNote instead of deleting the whole highlight). Usage is only implied by the tool name; the pointer to ListHighlights lives in the schema, not the description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes further by disclosing the exact destruction scope (item plus highlights), the tag side effect (tags removed from item but not deleted), and irreversibility ('This can't be undone'). This is precisely the behavioral context a destructive tool needs, and it is consistent with 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 sentences, front-loaded with the action, then side effects, then alternatives. Every clause earns its place with no redundancy.

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

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

Output schema exists, so return values need no explanation. For a single-param destructive tool, the description covers action, cascade effects, irreversibility, and alternatives — everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the single parameter's description already gives the ID format and pointer to ListItems/SearchLibrary. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('permanently delete an item') plus the cascade scope ('along with its highlights') and tag semantics. It clearly distinguishes itself from DeleteTag and UpdateItem by naming both siblings and the behavior that separates them.

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

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

Explicit routing: tags themselves are kept and DeleteTag is the tool for that, while archiving via UpdateItem is named as the non-destructive alternative. Both when-to-use and when-not are stated, leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true and non-readOnly, so the safety profile is carried structurally. The description adds genuinely useful context beyond that: irreversibility ('can't be undone') and the side effect that items survive while the tag is detached from all of them. The only minor gap is that it doesn't note the idempotency explicitly, though annotations cover 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?

Three short sentences, front-loaded with the core action and its permanent nature. Every clause earns its place: action, side-effect, irreversibility, 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 single-param destructive tool with a full schema, complete annotations, and an output schema present, the description supplies everything an agent needs: action, irreversibility, side effect on items, and the sibling routing. Nothing material is missing.

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

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

Schema coverage is 100% – tag_id is documented in the schema, including a format example and a pointer to ListTags. The description adds nothing about the parameter beyond what the schema already says, so the baseline 3 is appropriate.

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

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

States a specific verb (permanently delete) and resource (a tag), with a scope clarification that the tag is removed from every item while items are kept. This distinguishes it from the sibling RenameTag and from the item-level RemoveTag.

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

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

Explicitly routes the agent to the correct alternative: 'to untag a single item, use RemoveTag instead.' Combined with 'permanently delete', the when-to-use and when-not-to-use conditions are both clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds the nature of the returned data (per-operation rate limits and remaining read quota), but that content is also captured by the output schema, and it says nothing about auth requirements or quota-exhaustion behavior.

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

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

A single front-loaded sentence with the resource first and the payload second. The parenthetical enumerating which rate limits are returned is slightly verbose but does real work by telling the agent exactly what diagnostic data is available.

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 tool with an output schema and full annotation coverage, the description carries the remaining burden well and need not restate return values. The only gap is the absence of any guidance on when checking account quota is worthwhile.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool applies. The description correctly implies the call is unconditional and scoped to the connected account.

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 ('Get') and resource ('the Matter account the server is connected to'), then enumerates what the response contains. None of the sibling tools deal with account state, so the agent can distinguish this from item/tag/highlight operations without opening a schema.

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

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

Usage is only implied: an agent infers this is the call to make when it needs account identity or rate-limit/quota state. There is no explicit when-to-use statement, no exclusions, and no mention of how it relates to the sibling read tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and idempotency profile is covered. The description adds the metadata-vs-content distinction, but nothing about pagination, auth, or behavior on a missing ID.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the sibling routing immediately after. 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?

With an output schema present, the description need not enumerate returned fields, and the single required parameter is fully documented in the schema. It is complete for invocation, though it could note what 'metadata' broadly contains.

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%; the schema already documents item_id format ('itm_r9f3a') and how to discover it via ListItems or SearchLibrary. The description only restates 'by ID', adding no meaning 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?

States a specific verb and resource ('Get a single item's metadata by ID') and explicitly scopes it to metadata rather than body text, distinguishing it from GetItemContent and GetItemWithHighlights without needing to open their schemas.

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

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

Names the alternative (GetItemContent) and the condition that selects it ('for the full text'), which is real routing guidance. It does not mention GetItemWithHighlights, so one sibling relationship is left unaddressed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavioral context they cannot: a hard rate limit of 20 full-text fetches per minute and chunked Markdown output. It does not describe pagination termination beyond the schema's next_offset hint, so it stops just short of fully rich disclosure.

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

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

Two tight sentences, front-loaded with what the tool returns and immediately followed by the constraint that governs its use. 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?

An output schema exists, so return values need no explanation. The description covers format, chunking, the rate limit, and routing to cheaper siblings, leaving nothing an agent needs 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 item_id, offset, and max_chars are already documented in the schema. The description reinforces chunking and max_chars but adds no syntax or constraint detail beyond what the schema provides; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource+format: 'Get an item's full text as Markdown, in chunks of up to max_chars.' It also distinguishes itself from siblings by naming ListItems and GetItem as the lighter excerpt alternatives, 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?

Explicitly names the alternative tools (ListItems, GetItem) and the condition that selects them ('use excerpts ... when they're enough'), plus the rate-limit constraint that motivates restraint. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so safety is covered. The description adds genuinely useful behavioral detail beyond that: the result is capped at 100 highlights/notes and is fetched in two requests, which hints at latency and truncation behavior.

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

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

Two tight sentences with no waste; the core behavior and its limit are front-loaded before the usage example. 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?

An output schema exists, so return values need not be explained, and the single parameter is fully documented. The description covers what an agent needs for this simple read tool, though it could note what happens when more than 100 highlights exist (truncation vs pagination).

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?

Only one parameter (item_id) and schema description coverage is 100%, so the schema already explains the ID format and how to obtain it via ListItems/SearchLibrary. The description adds nothing further about the parameter, which is the expected baseline at full 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?

States a precise verb and resource ('Get an item together with every highlight and note on it') and scopes it with a cap ('up to 100'). This clearly distinguishes it from siblings like Matter_GetItem (item only) and Matter_ListHighlights (highlights only).

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 a concrete use case in the form of a user question ('what did I highlight in this article?'), which tells the agent when this tool is appropriate. It does not explicitly name alternatives like GetItem or ListHighlights or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only that notes are returned alongside passages; it says nothing about pagination limits or ordering, though the schema carries pagination. Baseline 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?

A single efficient sentence with the resource and scope front-loaded and zero padding. Every clause ('one item', 'with any notes they added') carries information.

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

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

With a full output schema and annotations covering safety and idempotency, the description only needs to convey purpose and scope, which it does adequately. Minor gap: it does not clarify ordering or how this differs from GetItemWithHighlights, which is the one ambiguity an agent would face.

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%: item_id, limit (1-100) and cursor are all documented in the schema, including guidance to find item_id via ListItems or SearchLibrary. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the passages the user highlighted') and scopes it to 'one item', with the extra detail that attached notes are included. It separates itself reasonably from the broader ListRecentHighlights, though it does not explicitly name the overlapping GetItemWithHighlights sibling.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite several siblings (Matter_GetItemWithHighlights, Matter_ListRecentHighlights) that cover similar ground. The 'in one item' phrasing implies a scoping condition but leaves the agent to infer which sibling to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds only the filtering scope, not pagination defaults or truncation behavior; a 3 is appropriate given the annotation coverage.

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

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

Two sentences, zero waste, with the core capability front-loaded and the alternative routed in the second sentence.

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 an output schema present, return values need no explanation, and annotations carry the safety profile. The description is complete enough for correct invocation, though it could note the default order/page size behavior for an 8-parameter list tool.

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

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

Schema description coverage is 100% and every parameter (limit ranges, enum meanings for order/status, tag_ids usage, cursor paging, updated_since semantics) is already documented in the schema. The description adds no syntax or default-value detail beyond it, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (items in the user's Matter library) and enumerates the filter dimensions (status, favorites, tags, content type). It also names the sibling it is not, SearchLibrary, so an agent can distinguish the two without opening either schema.

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

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

It gives an explicit routing rule for the alternative (use SearchLibrary for word/title/author/site matches), which is the main disambiguation an agent needs. It does not state prerequisites or explicit exclusions (e.g. that this returns metadata rather than full content), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds useful content semantics (newest-first ordering, session = one timed reading period, multiple sessions per day) but no pagination, auth, or rate-limit behavior beyond what the cursor parameter already documents.

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

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

Two sentences, zero filler, and the most decision-relevant facts (what is listed, ordering) are front-loaded before the clarifying definition of a session.

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 rich annotations, a full input schema, and an output schema covering return values, the description needs only to frame ordering and granularity, which it does. Pagination behavior is conveyed by the cursor parameter in the schema, so 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%, with limit, since, and cursor each documented in the schema itself. The description adds no parameter interpretation, so the baseline 3 for a fully-documented schema 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 gives a specific verb and resource ('List the user's reading sessions') plus ordering ('newest first') and a precise definition of a session as a timed reading period, which implicitly separates it from aggregate siblings like SummarizeReadingTime. It never names an alternative sibling, so differentiation relies on inference rather than explicit 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?

There is no when-to-use, when-not-to-use, or alternative-routing guidance; the description only states what the tool returns. An agent must infer from the name alone that this is the right call versus ListRecentHighlights or SummarizeReadingTime.

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

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

With annotations already covering read-only, idempotent and non-destructive behavior, the description adds genuinely new operational context: the request budget ('one request for recently updated items and one per item checked (at most 21 requests)') and a correctness caveat that reading progress and tag changes also count as updates, so some highlighted items may go unchecked when more_items is set.

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, front-loaded with the purpose and use case, followed by the cost model and caveat. Every sentence carries information an agent needs; none is filler.

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

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

An output schema exists, so return values need no explanation. For a read-only list tool the description supplies purpose, trigger, request cost and a partial-results caveat, leaving no material gap 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% and both parameters are fully documented there, including the 7-day default for 'since' and the 1-20 range for max_items. The description reinforces the cost of max_items ('one per item checked') but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb, resource and temporal scope: 'List the highlights the user made recently, grouped by item.' The 'recently'/'grouped by item' qualifiers implicitly separate it from the sibling Matter_ListHighlights, but no sibling is named explicitly.

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

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

Gives a concrete usage trigger — 'Use this to answer "what did I highlight this week?"' — which is more than implied context. It does not, however, state when NOT to use it or name ListHighlights as the alternative for full-history queries.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the useful behavioral detail that each tag is returned with an item count, but does not mention pagination or return format, which is somewhat covered by the output schema.

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

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

A single efficient sentence that front-loads the verb and resource and includes the most valuable scope detail. No redundancy or 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?

Given two simple parameters, full annotation coverage, and the presence of an output schema, the description is nearly complete. It could optionally mention pagination or that it returns tags with counts, but the core purpose is clear and the schema handles the rest.

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

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

Schema description coverage is 100%, and both parameters (limit, cursor) are fully documented in the schema, including pagination semantics. The description adds no parameter-level information, which is acceptable given the schema already covers everything.

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 ('List') and resource ('the user's Matter tags') plus a scope detail ('how many items each one is on'). This distinguishes it from tag-mutation siblings like AddTag, DeleteTag, and RenameTag, but does not distinguish it from other list siblings such as ListItems or ListHighlights.

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?

No guidance on when to use this tool versus alternatives or when not to use it. The broader family context (tag CRUD vs. item listing) is left for the agent to infer.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by clarifying what is NOT destroyed: the tag definition and its associations to other items survive, which is the key question an agent has about a removal 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 short sentences with zero filler; the action and its scope come first, and the preservation guarantee follows 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?

For a simple, idempotent two-parameter unlink operation with full schema coverage, complete annotations and an output schema, the description supplies everything an agent needs. Only an explicit pointer to the contrasting sibling (DeleteTag) 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%; both parameters carry examples and even discovery hints ('Use ListTags to find it', 'Use ListItems or SearchLibrary to find it'). The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

Specific verb (Remove) plus resource (tag) with explicit scope limiting the operation to 'one item'. The clause 'The tag itself and its other items are kept' implicitly separates it from Matter_DeleteTag, though it never names a sibling explicitly.

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

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

The phrase 'from one item' implies the correct use case (unlinking a tag from a single item rather than deleting or bulk-removing), but there is no explicit when-to-use, when-not-to-use, or named alternative such as Matter_DeleteTag or Matter_AddTag.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact — the rename propagates to every place the tag is used — but says nothing about auth requirements, failure modes (e.g. name collisions beyond the schema note), or side effects on tagged items.

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 eight-word sentence with the action and its scope front-loaded. Nothing is padded or redundant.

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

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

With an output schema present, a fully described input schema, and annotations covering the safety profile, the description only needs to convey scope — which it does. The remaining gap is the absence of any when-to-use routing against sibling tag tools.

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

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

Schema coverage is 100%, so both tag_id and name are already fully documented, including the uniqueness constraint and a pointer to ListTags. The description contributes no additional parameter detail, so the baseline 3 applies.

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

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

States a specific verb (Rename) and resource (tag), plus a scope qualifier ('everywhere it's used') that meaningfully distinguishes it from Matter_AddTag, Matter_RemoveTag and Matter_DeleteTag. It does not name a sibling explicitly, so it falls 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 guidance on when to choose this over Matter_AddTag or Matter_DeleteTag, nor any prerequisite context. Usage is only implied by the verb, which is the minimum for a rename tool surrounded by other tag operations.

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

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

Annotations only declare the generic profile (idempotent, non-destructive, open-world); the description adds the operationally important behavior: extraction is asynchronous and takes roughly a minute, an already-saved URL returns the existing item unchanged with already_in_library: true, and status selects queue vs archive. That is real disclosure beyond the structured fields.

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

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

Three sentences, zero filler, and the core action plus the async caveat are front-loaded before the dedup and relocation details. Every sentence carries distinct 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?

An output schema exists, so return-value documentation is not required, yet the description still surfaces the one return field an agent must branch on (already_in_library). Async timing, dedup semantics, and follow-up routing are all covered.

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

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

Schema description coverage is 100% and the enum values are already documented in the schema, so the schema carries the parameter burden. The description adds only indirect meaning (that status placement can later be changed via UpdateItem) and says nothing about URL format or constraints. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Save a URL to the user's Matter library') and implicitly distinguishes itself from the read siblings (GetItem) and the mutation sibling (UpdateItem). An agent can identify it as the write-entry-point for the library without opening any schema.

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

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

Explicitly names when to follow up ('check GetItem later if processing_status is processing') and which alternative to use for relocation ('use UpdateItem to move it'), plus the condition that selects the no-op path (already saved). When-to-use, when-not, and the alternative are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: relevance ranking and the fact that unsaved (in_library:false) hits are unusable downstream. It omits pagination/cursor behavior, which keeps it from a 5.

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

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

Two sentences, zero padding, with the core capability front-loaded and the downstream constraint second. Every clause carries information an agent can act on.

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

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

An output schema exists, so return values need not be restated, and the description supplies the one thing the schema can't: that unsaved hits can't be chained into item tools. It stops short of describing pagination or default scope handling, leaving a small gap for a 4-param tool.

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

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

Schema description coverage is 100%, so all four parameters including the query operators and the scope enum are already fully documented. The description's mention of searchable fields ('full text, title, author or site') loosely mirrors the by:/site:/title: operators but adds no syntax or format detail. Baseline 3 applies.

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

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

States a specific verb and resource ('Search the user's Matter library') plus the indexed fields and relevance ranking, so the operation is unambiguous. It does not, however, distinguish itself from sibling read tools like Matter_ListItems or Matter_GetItem, which is what would push this to 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?

Usage is implied by 'Search ... by full text, title, author or site' rather than stated, and no alternative (ListItems, GetItem) is named. The one real guideline offered is the caveat that in_library:false results can't be consumed by item tools, which is useful but only covers one edge case.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is largely covered. The description still adds value by explicitly saying the operation can replace or remove an existing note (a mutation of prior state) and by clarifying that highlights themselves cannot be created via this API.

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

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

Two short sentences, front-loaded with the operation set, with zero filler. Every clause carries information an agent needs.

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 an output schema present and annotations covering the safety profile, the description only needs to convey purpose, mutation semantics, and scope limits — all of which it does. It could go further by naming the sibling used for the alternative operation, but nothing essential is missing.

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

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

Schema description coverage is 100%, and the schema already documents both parameters, including the empty-string-to-remove convention. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

Names a specific resource (the note on a highlight) and all three operations (add, replace, remove) in a single clear sentence. It also states a scope boundary ('Matter's API can't create highlights'), which distinguishes it from any highlight-creation intent, though it never names a sibling tool as an alternative.

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 implied usage context by pointing to ListHighlights for obtaining the highlight_id, and the note parameter implicitly defines the remove case. There is no explicit when-to-use/when-not guidance versus siblings like Matter_DeleteHighlight or the tag tools.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: a cost signal ('Makes up to 10 requests') and the conditional rule that the current streak is only reported when the period reaches yesterday or today.

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

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

Front-loaded with purpose, then the output inventory, then usage examples and the request-cost note. The output enumeration is somewhat long, and since an output schema exists it partly duplicates structured data, but it remains readable and every clause is informative.

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 aggregation tool with a full output schema, the description covers purpose, trigger questions, cost, and the streak-reporting condition. The only minor gap is no explicit routing against ListReadingSessions, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents since/until/timezone_name with defaults and formats. The description adds no parameter syntax or defaults beyond what the schema provides, aside from the implicit linkage of 'until' to the streak behavior. Baseline 3 applies.

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

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

Specific verb (summarize) plus resource (reading time over a period), and it enumerates exactly what the summary contains: totals, averages, days read, longest streak, busiest day, current streak. This clearly separates it from Matter_ListReadingSessions, which returns raw sessions rather than aggregates.

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

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

Gives concrete user-question triggers ('how much have I read this month?', 'how much did I read in September?'), which tells the agent when to reach for this tool. It stops short of explicitly naming the raw-session alternative (ListReadingSessions) and when to prefer that instead.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, so the safety profile is covered by structured data. The description adds the useful 'at least one change' constraint, but says nothing about what a partial update does to untouched fields or whether archive is reversible (that detail lives in the schema, not the description). No contradiction with annotations.

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

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

Two sentences, front-loaded with the primary operations followed immediately by the invocation constraint. Nothing extraneous and nothing buried.

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 an output schema present and rich annotations, the description need not explain returns. It covers the operation set and the minimum-change requirement, though it omits any note about partial updates or reversibility that would fully round out a multi-field mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents item_id, status enum, favorite, and progress_percent in detail. The description's listing of change types roughly mirrors the parameters and adds no format or edge-case detail 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 names specific verbs and the resource: archive/re-queue an item, favorite/unfavorite it, set reading progress. That clearly separates it from tag tools (AddTag/RemoveTag) and DeleteItem/SaveItem siblings. It stops short of naming any sibling or scope boundary explicitly, so it earns a 4 rather than 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?

'Pass at least one change' gives a concrete invocation constraint, which implies the tool is for one-off state changes rather than bulk or tag operations. However, it never states when to prefer this over SaveItem, DeleteItem, or the tag tools, so usage is only implied.

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