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

With no annotations, the description carries the full burden and does well: it discloses copy (not move) semantics, that only supported images are accepted, that the inbox is fixed, and that stale revisions are rejected (optimistic-concurrency behavior). It omits error/response behavior and permission requirements, keeping 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?

Three tight sentences, front-loaded with purpose then source rules then the revision requirement. No filler, and the most important constraint is stated first.

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

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

For a 6-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the critical source and concurrency rules but says nothing about caption, experienced_at, id, or the outcome of the operation.

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%, so the description must compensate. It adds real meaning for source_path (delivered by the channel message) and attachment_token (from list_pending_attachments), and explains expected_revision, but leaves id, caption, and experienced_at entirely undocumented.

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 (copy), resource (one supported image), source (fixed attachment inbox) and destination (an existing vault entry). This clearly distinguishes it from read-only siblings like get_attachment and list_pending_attachments.

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

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

Explicitly tells the agent which sources are acceptable (a path from the current channel message, or a token from list_pending_attachments) and warns against invented paths, naming a sibling tool. It also gives the precondition of supplying the revision from the latest read. It does not spell out when not to use it, so it falls just short of 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?

No annotations are provided, so the description carries the full disclosure burden for a write tool. It does add one genuinely useful behavior not in the schema: duplicate-title handling (repeated experience titles allowed, others rejected). However, it says nothing about permissions/auth, what happens on rejected duplicates, or the response, leaving significant gaps.

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 tightly written sentences, front-loaded with the core action and followed by the duplicate-title rule. No filler, though the type enumeration is somewhat long relative to the information it conveys.

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 19-parameter, zero-required, no-annotation, no-output-schema tool, the description is far too thin. It omits conditional requirements (text required unless type=books/book), the nested attributes shape, tag/relation semantics, and uniqueness/error behavior beyond titles.

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 0% across 19 parameters, so the description is obligated to compensate and largely does not. The enumerated types loosely map to the `type` enum, but key fields (attributes, relations, unresolved_relations, title uniqueness, the required text/attributes conditionals, kind enums) are unexplained.

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

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

The description names a specific verb ('Capture') plus an explicit enumeration of captureable resource types, and the 'non-URL' qualifier implicitly routes URL content away to save_bookmark. It is clear what the tool does, though it does not name any 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 'non-URL' phrase hints that this is not for bookmarks/links (implying save_bookmark), which is the only usage signal present. There is no explicit when-to-use/when-not statement or named alternative among the many siblings.

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 no annotations, the description carries the full burden and only partially discharges it. It usefully discloses the blocking rule for unresolved relations, but says nothing about reversibility, idempotency, required permissions, or what happens when the operation fails.

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 waste. The core action is front-loaded and the blocking caveat 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?

This is a mutation tool with no annotations, no output schema, and two undocumented parameters, so the description is the only behavioral source and it omits concurrency behavior, failure modes, and return information. It is under-specified for its complexity.

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

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

Schema description coverage is 0% and the description explains neither parameter. The 'expected_revision' parameter is a concurrency token whose semantics matter a great deal and are left entirely unstated; only the form of 'id' is inferable from the pattern.

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 ('Mark ... as reviewed') and resource ('review item'), scoped to a single item. It is clear against 'review_queue' (listing) but doesn't explicitly name or differentiate itself from siblings like set_status or validate.

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 'Unresolved relations still block completion' implies a precondition for successful use, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the many sibling 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?

No annotations are provided, so the description carries the disclosure burden; it does state "This is read-only" and names the returned content, which are useful. However, it says nothing about authentication, behavior for unknown/uninstalled types, or error conditions.

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 the core purpose front-loaded and no filler. The read-only note is appended efficiently rather than padding the opening.

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 one-parameter describe tool with no output schema and no annotations, the description reasonably covers what is returned and the safety profile. It falls short on parameter format and usage context, leaving gaps an agent must resolve elsewhere.

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 0% and the single required type_id has only a regex pattern, no textual description. The word "qualified" hints at a namespace/name form matching the pattern, but the description never explains the expected format or how to obtain a valid type_id.

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 ("Describe") and resource ("one installed qualified schema type") and enumerates the output content (fields, body sections, generated JSON Schema). It is clear what the tool does, though it does not explicitly contrast with the sibling list_types (list vs. describe).

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 guidance, no prerequisites, and no mention of alternatives such as list_types to enumerate types. The agent is left to infer that this is for retrieving detail on a single already-known type.

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 no annotations, the description carries the full burden. It usefully discloses output character ('No bodies,' names/URLs only) and an epistemic caveat that matches are not proof of identity, but says nothing about pagination behavior, permissions, cost, or side effects.

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

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

Three short sentences with the purpose front-loaded and zero filler. The clipped style ('No bodies.') is efficient, though the final fragment is terse enough to be slightly ambiguous on first read.

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

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

There is no output schema and no annotations, so the description must cover more ground than it does. It partially describes the response (names and URLs, no bodies) but omits pagination guidance for the limit/offset parameters and gives no sense of result ordering or match quality.

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 0%, so the schema documents no parameters. The description conveys that the required id targets 'one entry,' but limit and offset are entirely unexplained (page size vs. offset semantics), and the id's expected format is left to the regex alone.

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

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

States a specific verb and resource: 'Suggest possible duplicates or related titles for one entry,' which clearly separates it from siblings like get_entry, merge_entries, and search. It does not explicitly name an alternative tool, but the dedupe-suggestion intent is unambiguous.

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

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

Usage is implied by 'for one entry' and the caveat that results are 'evidence for review,' suggesting a human-in-the-loop dedupe workflow. However, it never says when to call this versus search, retrieve, or merge_entries, nor what preconditions the entry must meet.

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 no annotations, the description carries the full behavioral burden. It discloses important traits: image content is returned for display, path and unreferenced-blob access are impossible, large images are refused rather than truncated, and a host-configured outbox may return delivery_path and delivery_marker. It does not cover auth requirements or error behavior for missing entries.

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 content is front-loaded with the core purpose, followed by constraints, usage, and edge behavior. Sentences are informative and mostly earn their place, though the outbox and large-image details make it slightly dense for a two-parameter getter.

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 no annotations, no output schema, and 0% schema description coverage, the description does a good job covering purpose, usage, constraints, and edge behavior. It remains incomplete on explicit id parameter meaning and error conditions, but is largely sufficient 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 description coverage is 0%, so the description must compensate. It explains attachment_id as coming from the entry's own attachments and clarifies the entry-based relationship, but it does not explicitly explain the id parameter beyond 'that entry'. The schema patterns provide format constraints, but semantic meaning is only partially described.

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

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

The description states a specific verb and resource: 'Return one image already attached to an entry, as image content the channel can display.' It distinguishes this from path-based file access and unreferenced blobs, which helps an agent separate it from siblings like add_attachment or get_entry.

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 a clear usage condition: 'Use it when the user asks to see a photo that is stored.' It also implies when not to use it by stating it cannot address files by path. However, it does not explicitly name alternative tools or describe exclusion scenarios beyond that constraint.

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 no annotations, the description carries the full behavioral burden. It discloses a genuinely non-obvious trait: relations are split into held vs. replaced, and as_of moves both to an earlier instant, which is valuable behavioral context. However it omits error behavior for missing/inactive IDs, pagination (none needed), and what happens to relations when as_of is used beyond shifting the instant.

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 the core purpose before the relation/as_of nuance. No filler or repetition.

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

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

For a two-param read tool with no output schema, no annotations, and 0% schema coverage, the description covers purpose and one behavior (relation splitting/as_of) but leaves id constraints and inactive/missing-entry behavior unaddressed, which an agent could need before calling.

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 0%, so the description must compensate. It does explain as_of semantics (moves relation state to an earlier instant), which the schema does not, but says nothing about the required id format or the pattern/length constraints. The as_of explanation adds real value, but id remains undocumented, so it's borderline.

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

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

States a specific verb (Read) and resource (one selected active entry, including body) by stable ID. This clearly distinguishes it from siblings like list_types, search, or inventory that enumerate rather than fetch a single record, though it doesn't explicitly name 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?

No explicit when-to-use guidance, no conditions or exclusions, and no named alternatives. The phrase 'selected active entry' implies the ID must reference an active entry but doesn't say what to do for inactive ones or which sibling to use for search vs. direct fetch.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses read-only semantics, that there is no entry-result limit, and that no titles or bodies are returned. It omits auth requirements and any cost/performance note, so a 3 is appropriate rather than higher.

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

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

Three tight sentences with the core purpose front-loaded and no filler. Each sentence adds a distinct fact (scope, read-only/limits/return shape, as_of semantics). Minor cost: the as_of sentence is abrupt and assumes the reader knows what relation_count is.

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

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

With no output schema, the description correctly takes on return-value disclosure: it states the tool yields aggregate counts, no titles or bodies, and mentions relation_count. Combined with the simple one-param surface, an agent has enough to call it, though the as_of format remains unspecified.

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?

One parameter (as_of) with 0% schema description coverage, so the description must compensate. It does add meaning — 'relation_count is what holds now, or at as_of' — clarifying the temporal effect of the parameter. However, it never states the accepted date/time format or that omitting it means 'now', leaving a real gap.

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+scope: 'Return complete aggregate counts for every active vault entry.' An agent can clearly distinguish this from content-returning siblings like get_entry, retrieve, or search. It does not explicitly name a sibling, so it stops short of 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?

No explicit when-to-use or when-not-to-use guidance and no named alternatives. Usage is only implied by the scope ('aggregate counts', 'returns no titles or bodies'), which hints you should pick this when you need counts rather than content. Adequate but leaves routing 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?

With no annotations, the description carries the full burden and does so well: it discloses that returned tokens are short-lived and opaque, that source paths are never exposed, that results are oldest-first, and that identical content is collapsed with sha256/duplicate_count. It omits any statement about permissions, rate limits, or failure modes, keeping it out of 5 territory.

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

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

Front-loaded with the core purpose, then behavior. Dense but every sentence adds information; the dedup/duplicate_count explanation is longer than strictly needed but earns its place by preventing a misread of duplicate results.

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 annotations, the description steps up and explains the return shape (tokens, ordering, dedup semantics), which is exactly what is needed. The remaining gap is the two parameters, which are left undocumented in both schema and description.

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 0%, and neither 'limit' nor 'max_age_seconds' is explained in the description. Only 'received recently' loosely hints at max_age_seconds and 'oldest first' loosely implies limit semantics; the agent gets almost no guidance on how to set these two bounded integers.

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 supported images ... in the server's fixed attachment inbox'), which is clearly distinct from the mutation/query siblings like get_attachment and add_attachment. It does not explicitly name a sibling to contrast with, 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?

Gives an explicit trigger condition: 'Use this when the channel supplied image pixels but no usable IMAGE path.' That is a concrete when-to-use statement. It stops short of explicitly ruling out the alternative (e.g., when to use get_attachment instead), so a 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?

With no annotations, the description carries the full burden. It does usefully disclose a behavioral trait beyond the name: entries are returned without their bodies, which warns the agent not to expect full content in the results. However, it says nothing about ordering, pagination, retention windows, or whether the operation is a safe read.

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 no filler, and the most decision-relevant detail (the missing bodies) is placed where it will be read first.

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-param list tool with no annotations and no output schema, the description is minimally adequate: it says what is listed and one property of the result. It omits what fields a listed entry actually exposes (id, title, deletion time), how results are ordered or paginated, and how to act on a result, which an agent needs since no output schema exists.

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 no parameter semantics burden to discharge; the baseline of 4 applies. The description cannot and need not add parameter detail.

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 trashed entries') and adds a scope qualifier ('without their bodies'). An agent can tell this is the trash listing, but the description does no work to distinguish it from siblings such as get_entry (for trashed content), search, or restore.

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 guidance, no prerequisite, and no named alternative. The agent must infer on its own that this is for browsing deleted items and that get_entry/restore are the follow-ups for inspecting or recovering a specific trashed entry.

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 no annotations provided, the description carries the full burden and does disclose the key behavioral trait: 'This is read-only and does not return vault content.' That safety/scope statement is valuable. It stops short of covering error behavior, permissions, or the shape of the returned list, so it is only a partial 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 with zero waste. The core purpose is front-loaded, and the scope constraint follows immediately. Appropriately sized for a zero-parameter list tool.

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

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

For a simple read-only listing with no output schema and no parameters, the description covers purpose and the important negative constraint (no vault content). It could say more about the return structure now that no output schema exists, but for a low-complexity tool it is nearly sufficient.

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 is 4. There is nothing for the description to clarify beyond the empty schema, and it correctly does not gesture at nonexistent inputs.

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 installed declarative schema packs and their qualified type IDs.' An agent can tell what it retrieves. However, it does not distinguish itself from the closely related sibling 'describe_type', leaving the boundary between listing and describing types to inference.

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. The obvious sibling 'describe_type' is never mentioned, nor is there any indication of when an agent should call list_types instead of inventory or describe_type. Usage is left entirely 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?

No annotations are provided, so the description carries full behavioral burden. It usefully discloses that vault content is not read (a side-effect/safety-relevant trait), but says nothing about permissions, pagination, ordering, or what happens on an empty result.

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 no filler; the scoping constraint is attached directly to the action. Every word earns its place.

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

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

For a zero-parameter read tool this is close to adequate, but with no output schema the description could say what a listed view looks like (names/identifiers) so an agent knows how to feed one into run_view. The meaning of 'declarative saved search view' is also left unexplained.

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 and the schema has 100% coverage with additionalProperties false, so there is nothing for the description to clarify. Baseline 4 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 (declarative saved search views), and the qualifier 'without reading vault content' scopes it as a metadata-only operation. It is distinguishable from run_view, though it never names that sibling to make the boundary explicit.

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: the phrase 'without reading vault content' suggests this is the cheap discovery step before run_view, but no when-to-use condition, prerequisite, or alternative is stated. An agent must infer the list-then-run workflow from the sibling names alone.

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?

No annotations exist, so the description carries the full burden and does well: it discloses conflict refusal, that the source goes to reversible trash, that incoming edges follow the target, and the expected_plan digest verification step. Missing auth requirements, rate limits, and explicit statement of what happens when apply is false, but most key behaviors are covered.

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

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

Front-loaded with the core purpose, then progressively details the workflow, safety refusals, and the key warning. Every sentence earns its place with no filler.

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

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

For a 4-parameter mutation tool with no annotations and no output schema, the description covers the essential safety and workflow context: preview/apply flow, conflict refusal, reversibility, and edge behavior. It omits permissions, idempotency, and the shape of the preview response, but is otherwise complete.

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

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

Schema description coverage is 0%, so the description must compensate. It gives conceptual roles for source ('goes to reversible trash'), target ('incoming edges follow the target'), and expected_plan ('echo its expected_plan digest'), and implies the apply flag via 'before apply,' but does not specify formats, patterns, or defaults.

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 ('merge') and resource ('entries') with a precise scope ('conservative merge of two explicitly selected entries'). The warning about candidate suggestions implicitly distinguishes this from find_candidates, so an agent can tell it apart from siblings.

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

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

Provides clear workflow guidance: 'Review the complete plan before apply; echo its expected_plan digest,' and an explicit when-not condition: 'Never merge merely because a candidate suggestion matched.' No sibling tool is named explicitly as an alternative, but the context is unambiguous.

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 no annotations, the description carries the full burden but does disclose real behavioral traits: it returns both outgoing and 'derived incoming' relations and splits results into 'in force' vs 'superseded', implying temporal/versioning semantics. It says nothing about pagination, auth requirements, or result format, and never mentions the as_of parameter.

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 tightly-packed sentence with no filler and the resource front-loaded, though the dense jargon ('derived incoming', 'in force', 'superseded') trades brevity for ambiguity.

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

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

For a tool with no annotations, no output schema, and 0% parameter coverage, the description is too thin: it never explains as_of, never clarifies what 'derived incoming' means, and cannot describe the return shape since no output schema exists.

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 0%, so the description must compensate. It only loosely covers 'id' via 'one stable ID' and gives no meaning at all for 'as_of', leaving half the parameters (including a non-obvious temporal filter) undocumented.

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 ('Show') and resource ('outgoing and derived incoming relations') scoped to 'one stable ID', which is far more than a tautology. However, it does not differentiate itself from the read-oriented siblings get_entry or retrieve, and the meaning of 'derived incoming' is left unexplained.

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 guidance, no prerequisites, and no mention of the sibling mutation tools set_relation / set_unresolved_relation that write the relations this tool reads. Usage is only implied by the verb 'Show'.

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?

No annotations are provided, so the description carries the full burden. It discloses single-item scope ('exactly one') and non-overwriting behavior, which are useful constraints. However, it omits permissions, failure modes, and the role of the required expected_revision concurrency token, leaving significant behavioral gaps.

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 sentence, front-loaded with the verb, no wasted words. Every phrase contributes necessary scope and behavioral 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 mutation tool with no annotations, two required parameters, and no output schema, the description is too thin. It states the action but leaves parameter meaning and safety behavior to inference, so an agent cannot invoke it correctly without guessing.

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 0% for both required parameters. The description does not mention 'id' or 'expected_revision' at all, so their semantics (e.g., that expected_revision is likely an optimistic-concurrency token) remain undocumented. It fails to compensate for the schema gap.

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 ('Restore') and resource ('trashed entry'), plus scope ('exactly one') and destination ('original path'). This clearly distinguishes it from sibling tools like 'trash' (the reverse action) and 'list_trash' (read-only listing).

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

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

Provides clear context: use it to restore a trashed entry, with a non-overwrite constraint. It does not explicitly name alternatives or state when not to use it, but the context is sufficient for an agent to infer appropriate use.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does disclose concrete limits (max 10 entries, 100000 body characters) plus a nuance about tentative word-form candidates retaining match_kind=word_form. It does not state the read-only/reversibility profile or pagination behavior, but the bounds disclosure is meaningful and non-obvious.

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 front-loaded sentences that each carry information: purpose, alternative routing, and bounds plus a caveat. Slightly dense in the final sentence, but nothing is wasted.

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

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

For a 6-parameter tool with no annotations and no output schema, the description adequately covers purpose, routing, and return bounds, but leaves four parameters (rank, type, as_of, query) semantically unaddressed, which is a real 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 description coverage is 0% across 6 parameters, so the description must compensate, and it only partially does: it implies the bounds for limit (ten entries) and max_body_chars (100000 characters). The rank enum values, type enum, as_of semantics, and query matching behavior are left entirely undocumented.

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 (search active entries, return full bodies and metadata) and explicitly frames itself as the single-call substitute for search + get_entry. An agent can distinguish it from search and get_entry from the description alone.

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

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

Explicitly names the alternative pattern ('search followed by several get_entry calls') and the condition that selects this tool ('when the answer needs entry contents'). It also provides a verification caveat for word-form candidates, which is actionable usage guidance.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose one real trait: entry bodies are omitted from results. Beyond that it says nothing about ordering, default limit, or whether this is a read-only, side-effect-free operation, which matters for an unannotated tool.

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

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

One short, front-loaded sentence with no filler; the scoping clause ("without entry bodies") is placed where it is most useful. It is efficient, though the brevity is partly under-specification rather than tightness.

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 annotations, no output schema, and an undocumented parameter, the description should do more. It does not state ordering, result shape, or the default limit, so an agent cannot reliably predict the call's 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 single parameter "limit" has 0% schema description coverage and the description never mentions it, its default, or its maximum. With zero descriptive compensation, an agent cannot tell whether pagination must be driven manually.

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?

"List unfinished knowledge" gives a verb and a rough resource, and "without entry bodies" narrows the scope. However, "unfinished knowledge" is vague and never connects to the review-queue concept implied by the name, so the agent must infer the domain. It is distinguishable from siblings only weakly.

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 find_candidates, list_pending_attachments, or list_trash. No prerequisites or follow-up actions (e.g., complete_review) are mentioned, leaving routing entirely 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?

With no annotations, the description carries the full burden, but it does disclose meaningful behavior: the view is 'data-only' (no side effects), 'bounded', and that limit/offset 'may override its page size'. It stops short of stating permissions, whether the override is truncating, or what happens on an unknown name.

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

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

Two tight sentences with zero filler; the core action is front-loaded and the second sentence earns its place by defining a view and the pagination override.

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-style, 3-parameter tool with no output schema and no annotations, the description covers the action and pagination behavior but omits prerequisite workflow (configured views), failure behavior, and any auth context, leaving clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully documents the limit/offset override semantics and that name selects the view, but leaves the name pattern/regex constraints and offset's exact meaning (rows skipped) entirely to the schema.

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

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

States a specific verb and resource ('Run one configured saved view') and clarifies what a view is ('a bounded, data-only set of search filters'). An agent can distinguish it from list_views by the run/list verb pairing, though the description never explicitly names the 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 explicit when-to-use, when-not, or alternatives are given. It implies a view must already be configured, but the description never tells the agent to call list_views first nor when to prefer this over search or retrieve.

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 no annotations, the description must carry the behavioral load, and it does disclose two meaningful traits: page content is untrusted data and duplicate canonical URLs are rejected. It omits the return behavior, permission requirements, idempotency, and what happens to partial/blocked fetches, so significant gaps remain for a mutation tool.

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

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

Three front-loaded sentences: purpose first, then the two constraints, then the parameter instruction. Dense but each sentence carries information; 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?

A 19-parameter write tool with no annotations, no output schema, and 0% schema description coverage needs far more than three sentences. The description never explains the metadata model, the distinction between relations and unresolved_relations, or the effect of fetch_status, leaving the agent under-equipped 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 0% across 19 parameters, yet the description explains only one (untrusted_web_metadata). The many enum fields (sensitivity, fetch_status, bookmark_kind, reading_status) and structural fields (relations, unresolved_relations, aliases) get no semantic guidance in either place, so the description fails to compensate for the coverage gap.

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 clear verb+resource ("Save one enriched bookmark") and adds scope ("from supported, neutral metadata"). It does not, however, distinguish this from plausible siblings like capture or save_recipe, leaving the agent to infer which write path applies.

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 rather than stated: "Pass untrusted_web_metadata straight through from the fetcher reply" tells the agent the expected calling flow, and "duplicate canonical URLs are rejected" signals a precondition. There is no explicit when-to-use-this-vs-alternatives guidance or statement of 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?

With no annotations, the description carries full behavioral burden. It helpfully discloses two real traits: the source web page is untrusted (a security-relevant caveat) and duplicate normalized URLs are rejected. It omits what a successful save does with sensitive content, permission requirements, and the fate of supplied vs fetched 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?

Two dense, front-loaded sentences with no filler; the core save action plus key constraints come first. Slightly terse given the tool's complexity, but 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 15-parameter tool with no annotations, no output schema, and 0% schema coverage, the description is far too thin. It gives no guidance on enums (sensitivity, interest_status), nested relation structures, or return/error behavior beyond the dedup rejection.

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 0% across 15 parameters, so the description must compensate. It only clarifies 'url' ('exact public source URL') and the text/note distinction; the other 13 params (tags, aliases, relations, sensitivity, interest_status, cooking times, canonical_url, etc.) get no semantic explanation in either schema or description.

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

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

Names a specific verb ('save') and resource ('recipe') and states the primary input constraint (exact public source URL) plus metadata. It is clearly distinguishable from siblings like save_bookmark by the 'recipe' resource, though it never explicitly says how it differs from capture or save_bookmark.

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 'Save one recipe from an exact public source URL' implies the intended use case, and the dedup note hints at preconditions. However, there is no explicit when-to-use vs alternatives (capture, save_bookmark, update) despite many relevant siblings, leaving routing 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?

With no annotations, the description carries the full burden and does so well: empty query lists everything, empty hybrid can return tentative match_kind=word_form candidates that must be verified, results are a single stably sorted page with total/has_more/next_offset, and relation filters reflect current state or as_of. It never states read-only status or what "active" excludes, but the behavioral disclosure is otherwise unusually rich.

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

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

Front-loaded with purpose, then rank semantics, then pagination and the type-filter fallback, then relation-filter state semantics. Dense but each sentence carries distinct information; the rank explanation is long relative to its weight, which is the only real cost.

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 24-parameter tool with no annotations, no output schema, and 0% schema coverage, the description does cover the response shape and the highest-stakes semantics (rank, empty query, type fallback). It still leaves most filter parameters and the sort/limit/pagination controls unexplained, so it is not fully complete for the surface it exposes.

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 0% across 24 parameters, and the description compensates only partially: rank's three modes and default, empty-query behavior, type-filter fallback, relation filters, and as_of are explained in depth. The remaining filters (limit, offset, sort, explain, domain, min_rating, place_kind, product_kind, bookmark_kind, reading_status, experience_kind, interest_status, occurred/read date bounds, related_id, attribute_filters) get no explanation, leaving much of the surface undocumented in both schema and description.

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 active knowledge entries") and narrows scope with "active" and "structured filters", which separates it from trash/restore siblings. It also explicitly routes body/metadata retrieval to get_entry, so an agent can distinguish it from find_candidates, retrieve, and relations without opening another schema.

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

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

Gives explicit when-to-use guidance: prefer the default hybrid because "a multi-word question finds nothing under substring alone", use get_entry only for the body of a selected result, and when a type filter returns total 0 report without_type_filter rather than declaring nothing exists. That is when/when-not/alternative coverage in one place.

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?

No annotations exist, so the description carries the whole burden. It usefully discloses that a superseded relation 'stays stored and readable; it is closed, not deleted' – genuine destructive-behavior context. However, it omits the concurrency contract implied by the required expected_revision, whether 'remove' is reversible, and any error/permission behavior for a mutation tool.

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

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

Three tight sentences with the core action front-loaded and the trickier supersession semantics packed into the second. Minimal waste, though the temporal-validity sentence is dense enough to be broken up.

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

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

For an unannotated, 9-parameter mutation tool with no output schema, the description covers the most subtle behavior (close-not-delete, temporal validity) but leaves too much of the required-parameter contract and alternative-tool routing unstated to be fully self-sufficient.

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 0% across 9 parameters, so the description must compensate and largely does not. It clarifies valid_from, valid_until and supersedes, but leaves id, target_id, predicate, resolve_reference and the required expected_revision unexplained beyond their patterns.

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: 'Add or remove a typed relation between two existing entries', and adds the pending-reference resolution case. It distinguishes itself from write-style siblings like set_tags, though it never names the closest sibling (set_unresolved_relation), leaving that differentiation implicit.

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

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

The description explains what supersedes and valid_from/valid_until mean when adding, but gives no guidance on when to use this tool versus set_unresolved_relation, set_tags, or relations. No exclusions or preconditions are stated, so the agent must infer the routing.

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

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

With no annotations, the description carries the full behavioral burden. It conveys a mutation but says nothing about the required `expected_revision` optimistic-concurrency guard, whether omitted fields are left untouched, whether the call is idempotent, or what happens on a revision mismatch. For a write tool this is a meaningful gap.

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 no filler. It is appropriately sized, though the brevity leaves the substantive behavioral and parameter gaps unaddressed rather than being optimally 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?

Given a 5-parameter mutation tool with a required revision token, zero schema descriptions, no annotations, and no output schema, the definition is too thin. An agent lacks the information needed to satisfy the concurrency requirement or predict field-omission semantics.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does. It maps meaning onto the three status fields (lifecycle/reading/interest) and implies they are combinable via "and/or", but it explains neither the required `id` (kn_ pattern) nor `expected_revision` (sha256 concurrency token), which are exactly the parameters an agent can most easily 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 verb ("Change") and enumerates the three status axes it can mutate: lifecycle status, bookmark reading status, and place/product/recipe interest status. This is clear enough to distinguish it from a generic `update`, but it does not explicitly contrast itself with siblings like `set_tags` or `update`, which also appear to modify entry state.

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 reach for this tool versus `update`, `set_tags`, or `complete_review`. The "and/or" hints that one or more status fields may be set together, but there is no stated context, precondition, or exclusion to route the agent.

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 no annotations, the description carries the full behavioral burden. It implies a non-destructive add/remove semantic and that only active entries qualify, but says nothing about the concurrency contract implied by expected_revision, permission requirements, whether existing tags are preserved, or the shape of the result.

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 no filler, which is well-sized for a simple tag mutation. It is efficient, though the brevity comes at the cost of the missing detail scored elsewhere.

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 four-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage, one sentence is not enough. An agent lacks the revision/concurrency context and tag semantics needed to invoke it confidently.

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 0%, so the description must compensate for all four required parameters, yet it explains none of them. 'entry' loosely maps to id and 'add or remove' maps to action, but the critical expected_revision parameter and the tag list format/limits are not addressed at all.

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

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

The description names a specific verb pair (add/remove) and resource (tags) scoped to 'one active entry', so an agent understands the operation. It does not distinguish itself from the sibling 'update', which could plausibly also touch tags, but the purpose is otherwise unambiguous.

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

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

There is no explicit when-to-use guidance, no mention of when not to use it, and no routing to alternatives such as 'update', 'set_status', or 'set_relation'. The only hint is the implicit restriction to 'active' entries.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies mutation and a queued-review workflow but says nothing about optimistic concurrency (expected_revision), permissions, reversibility, or what happens when the id/revision is stale.

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 no filler, and the core action is front-loaded. It is arguably under-specified rather than over-long, so conciseness itself is good.

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 five-required-parameter mutation tool with no annotations and no output schema, one sentence is not enough. Details on the revision guard, id format, and predicate conventions are missing, leaving the agent under-informed before calling it.

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

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

Schema description coverage is 0% for all five required parameters. The description loosely covers the action ('add or remove') and the reference ('free-text'), but leaves id and especially expected_revision (a concurrency token) and predicate format entirely unexplained.

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 pair (add/remove) and resource (a grounded free-text relation reference) with a purpose (for later review). However, it gives no indication of how it differs from the sibling tool 'set_relation', and 'grounded free-text relation reference' is jargon that doesn't fully resolve what entity is being modified.

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 guidance, no exclusions, and no mention of the closely named sibling set_relation. An agent must guess whether this tool is for unresolved/pending relations versus confirmed ones based solely on the phrase 'for later review'.

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 no annotations, the description carries the full behavioral burden, and it does disclose the most important trait: the operation is reversible with a 90-day retention window. It says nothing about revision-conflict behavior, permissions, or what happens to an entry already trashed, which matters for a mutation tool with zero 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?

One sentence, no filler, and the core action plus its scope and reversibility are front-loaded. 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?

No annotations, no output schema, and 0% parameter documentation leave the agent without the semantics of expected_revision or reason, and without any indication of failure modes. For a mutating tool this is inadequate despite the useful reversibility note.

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

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

Schema description coverage is 0%, so the description must compensate, yet it explains none of the three parameters. 'Exactly one active entry' loosely gestures at the id, but expected_revision (optimistic concurrency) and reason are entirely undisclosed in both schema and description.

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 ('move ... entry to ... trash') and scopes it to 'exactly one active entry', which separates it from bulk operations and from the sibling restore/list_trash. It does not name a sibling alternative explicitly, so it falls just short of 5.

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

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

The phrase 'exactly one active entry' implies when this tool applies (single-entry retirement) and the 'reversible 90-day' framing hints that restore exists as the undo path, but no alternative or precondition is stated outright. Usage must be inferred rather than read.

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 no annotations, the description carries the burden and does disclose meaningful traits: append-only body semantics, deliberate absence of full-body replacement, and optimistic concurrency ('rejects stale changes'). It stops short of permissions, reversibility, or error/response behavior, but the concurrency and no-replace disclosures are genuinely useful beyond the schema.

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

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

Three sentences, no filler, with the allowable operations front-loaded before the constraints. The first sentence is a dense run-on list, but given 21 parameters it stays compact and every clause carries information.

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

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

For a 21-parameter mutation tool with no annotations and no output schema, the description covers motivation and concurrency but is thin on how the many optional fields interact (e.g. whether attributes replaces or merges, what rating/review do). It is adequate to start a call but not complete enough to invoke the richer fields confidently.

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 0% across 21 parameters, so the description must compensate and it only partially does — it names append, title, sensitivity, bookmark_kind, and gestures at experience metadata and record_experience. Numeric fields (rating, review, aliases, servings, cook_minutes, prep_minutes), source_* fields, attributes, and occurred_* fields are never explained, leaving a large share of parameters undocumented anywhere.

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?

Enumerates the concrete operations (append content, change title/sensitivity/bookmark kind/experience metadata, record a legacy place/product experience), which is much more specific than the bare name 'update'. The main weakness is that it never names the resource being updated (it is only inferable from the 'kn_' id pattern), so an agent must guess it mutates a knowledge entry.

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

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

States a real precondition ('Requires the revision from the latest read') and an exclusion ('Full-body replacement is intentionally unavailable'), which tells the agent a get_entry read must precede this call. However, it never contrasts itself with obvious siblings like capture, save_recipe, or save_bookmark, so when-to-use-this-vs-alternatives is left to inference.

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

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

With no annotations provided, the description carries the full burden but discloses little about behavior. It does not state whether the operation is read-only or mutating, what happens to invalid entries, whether it returns a report, or what permissions are needed.

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 no wasted words. It efficiently conveys the core operation without padding.

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

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

Given no annotations, no output schema, and no parameters, the description should do more to explain the validation's outcome, side effects, or usage context. An agent lacks enough information to call it confidently.

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

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

The tool has zero parameters, so the baseline score is 4. The description adds no parameter information, but none is needed given the empty input schema.

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

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

States a specific verb ('Validate') and resource ('active and trashed entries'), and names the criterion ('current vault rules'). It is reasonably distinct from siblings like update, trash, or restore, though 'vault rules' remains somewhat abstract.

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

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

Provides no guidance on when to use this tool versus alternatives such as review_queue, complete_review, or update. There is no mention of prerequisites, timing, or contexts in which validation should be run.

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