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

Annotations only declare readOnlyHint=false, so the description carries the burden of disclosure. It adds one genuinely valuable trait beyond annotations: reorder is semantically inert for completion. It says nothing about remove being destructive, what permissions are required, or how expected_revision guards concurrent mutations, which matters for a multi-variant 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?

A single front-loaded sentence with two clauses, each of which carries distinct information (scope, then the reorder caveat). Nothing is wasted and the most surprising constraint is placed after the scope statement where it reads naturally.

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 the missing pieces are not in the description but in the structured side: an output schema exists, so return values need no prose, and the schema enumerates all five actions with required fields plus the request_id replay contract and expected_revision. Because the structured fields cover what the prose omits, the description does the job it must do.

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 reported at 100%, so the baseline is 3. The description reinforces only two of the five action variants implicitly ('reordering columns', 'terminal flags') and does not explain add/remove/relabel or the expected_revision concurrency contract. It neither compensates for nor undercuts 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 clear verb+resource: 'Manage board columns and explicit terminal flags.' The resource (board columns/terminal flags) is specific and distinct from every listed sibling, which are all task/link/cloud oriented. It stops short of naming the concrete operations (add/remove/relabel/reorder/set_terminal) that the schema defines, so the agent still needs the schema to learn what 'manage' covers.

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 alternative among the 34 siblings. The clause 'reordering columns does not change completion semantics' gives a conditional cue about what this tool does and does not affect, which is a useful implied usage hint but not 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 supply only readOnlyHint=false, so the description carries nearly the whole burden. It never says what node is created, whether the operation is idempotent (the request_id/replay contract lives only in the schema), how slot-revision conflicts behave, or what errors occur on ambiguous NodeRefs.

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 well-formed sentence with zero filler, and the primary action is front-loaded. It is efficient, though efficiency here comes at the cost of coverage rather than from disciplined pruning.

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 7-parameter mutation tool with 14% schema coverage, an output schema, and dense sibling overlap (verdict, revise, note, task), one sentence is far short of what an agent needs. The output schema relieves the return-value burden, but parameter and routing gaps remain substantial.

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 14% across 7 parameters, so the description must compensate and largely does not. It gestures at evidence and the open-vs-verdict status split, but says nothing about initiative, about, options (slot/layer/expected_slot_revision), or the required text field's expected format.

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

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

It names two concrete actions (create an open hypothesis, save a reached verdict plus evidence) attached to a resource called a claim, so the broad purpose is graspable. But the dual-mode framing is never reconciled with what a 'claim' actually is, and nothing distinguishes it from siblings like verdict, note, or revise, which plausibly overlap.

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?

'or save an already reached verdict ... in one call' hints at an atomicity advantage over making separate calls, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling tools (verdict, revise, note). An agent has to guess whether this replaces or complements verdict.

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

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

The readOnlyHint already establishes this as a safe read operation. The description adds the useful scoping constraint that only one configured cloud is queried, but it does not cover behavior such as missing cloud configuration, return shape, or pagination.

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

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

The description is a single short sentence with the scope constraint front-loaded. It contains no redundant or filler text.

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

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

For a simple read-only list operation with annotations covering safety, the main missing piece is the meaning and expected values of the 'cloud' parameter. The description is minimally adequate but not complete for a caller unfamiliar with the configuration model.

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 explain the single 'cloud' parameter. It only says 'one configured cloud' and does not provide expected format, allowed values, or behavior when omitted, leaving the parameter meaning largely 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?

The description gives a specific verb ('List') and resource ('initiatives') scoped to 'one configured cloud.' It is clearer than the bare name, though it does not explicitly contrast with siblings like initiatives or clouds.

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 'in one configured cloud' implies that the caller must already have a cloud configured and should pick one, but it gives no explicit when-to-use guidance or alternatives such as the sibling initiatives tool.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add the remaining context—but 'resolve' leaves it unclear whether anything is mutated or returned. No return shape, no behavior on missing references, no mention of what 'existing' excludes.

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

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

A single short sentence with no filler, but its brevity comes at the cost of under-specification rather than efficiency.

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-required-parameter tool with zero schema documentation and no output schema, the description leaves too much unknown: parameter meaning, return values, and relationship to the multiple sibling cloud 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 description coverage is 0%, so both required parameters (initiative, name) are undocumented in both schema and description. The description never explains whether 'name' is the local node name or a cloud name, or what 'initiative' scopes.

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 resource ('cloud references of a local node') and a verb ('resolve'), but 'resolve' is ambiguous—it could mean look up, map to cloud IDs, or reconcile conflicts. It is not differentiated from siblings like clouds, link_cloud, or pull.

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

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

There is no guidance on when to use this tool versus link_cloud, clouds, cloud_recall, or pull, and no stated prerequisites. The agent must infer its role from the name 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?

readOnlyHint=true already establishes the safety profile, so the lower bar applies. The description does add real value by clarifying the non-importing semantics, but it leaves the 'existing paging contract' undefined and says nothing about result limits or ordering 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?

One sentence, front-loaded with the primary action and followed by the branching condition — no filler. The phrase 'existing paging contract' is mildly opaque jargon that assumes external knowledge, which keeps it from a 5.

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, so the description should carry more of the return-shape and paging burden, and the required 'initiative' parameter is never explained at all. Adequate to attempt a call, but an agent would need to guess on several parameters.

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 only 17% across six parameters, so the description must compensate. It usefully explains the id parameter's dual role and gestures at paging via 'paging contract,' but cloud, query, offset, and the required initiative parameter get no semantic explanation 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?

The description names a specific verb and resource ('Read a full shared cloud record') and distinguishes two modes: full read by id versus list/search. It separates itself from the nearby 'pull'/'clouds' siblings conceptually via 'without importing it,' though it doesn't name 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?

It gives one explicit routing rule ('by passing id, or list/search' — omit id to list), which implies when each mode applies. However, with siblings like pull, clouds, cloud_links, and link_cloud present, it never states when to prefer this tool over those, leaving the main ambiguity unresolved.

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

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

The readOnlyHint annotation already establishes the safety profile, and the description adds nothing beyond it — no mention of return shape, whether unconfigured clouds appear, ordering, or pagination. For a listing tool it is adequate only in the barest sense.

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

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

A single short sentence, front-loaded with the verb and with zero waste. Nothing could be trimmed without losing meaning.

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 with no output schema, the description is just enough to invoke the tool. It nonetheless leaves the agent guessing about what a configured cloud is and how the result relates to the output of cloud_links or cloud_initiatives.

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 document. Baseline 4 applies; no parameter semantics are missing.

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 configured clouds" gives a clear verb and resource, so the basic operation is unambiguous. However, with siblings like cloud_links, cloud_initiatives, cloud_recall, and link_cloud, the description never clarifies what a "cloud" is here or how this lister differs from those related tools.

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

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

There is no guidance on when to call this versus cloud_links or cloud_initiatives, and no stated prerequisites or exclusions. The agent must infer usage purely from the tool name.

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

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

The description adds some behavior beyond the sparse readOnlyHint=false annotation: it discloses that 'reminder delivery metadata' is recorded (consistent with a non-read-only tool), that graph output is compact/authorized, and that bodies are not returned. However, it says nothing about pagination despite a cursor parameter, budget behavior, or authorization requirements beyond the word 'authorized'.

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

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

Two compact sentences with no filler, and the core restore behavior is front-loaded before the view=graph guidance. The dense noun list in the first sentence is slightly opaque, 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?

This is a complex 9-parameter tool with conditional schema constraints, 0% parameter description coverage, and multiple view modes. The description addresses only a fraction of that complexity, leaving key parameters, view selection, and pagination behavior unexplained, even though the output schema means return-value details need not be 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 0% across 9 parameters, so the description carries the full burden, but it only explains view=graph and vaguely references selecting 'initiatives.' It leaves query, since, cursor, include, initiative vs. initiatives, recorded_at, budget_chars, and the other view modes completely 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?

The verb 'Restore' plus a list of resources (project rules, current records, open work, saved reasoning) gives a rough sense of the tool, but the scope is diffuse and overlaps heavily with siblings such as read, search, trail, and history. Only the graph-view sentence provides any differentiation, and even that is framed around output shape rather than the tool's core purpose.

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

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

The only routing guidance is 'Use view=graph for compact authorized structure... bodies remain in read,' which covers one view mode and implicitly points to the read sibling for bodies. There is no guidance on when to choose context over search, read, trail, history, or reference, nor any prerequisites for the other view modes.

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 readOnlyHint=false; the description adds real meaning by confirming it writes a downloadable artifact and that the destination stays inside the host artifact root. 'No history backup' also bounds the side effect. It omits what happens if the destination file already exists and whether auth/permissions are required.

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 short sentences, front-loaded with the primary action and output formats, then selection rules and constraints. No filler or restatement of the tool name.

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 not be described. For a 6-parameter, non-trivial oneOf tool the description covers formats, selection semantics, and destination scoping well. Overwrite/collision behavior and permission requirements are the remaining 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?

With 33% schema coverage and a complex three-branch oneOf, the description does valuable work: it spells out the initiative/initiatives/all mutual exclusivity and maps the format enum values to concrete outputs. The destination's location constraint is also restated in prose. request_id remains unexplained, but the schema documents it.

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

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

States a specific verb ('Export') and resource ('current knowledge') with the two output formats named inline. An agent can tell this is a file-export operation. It does not explicitly differentiate from siblings like share/pull/cloud_recall, which also move knowledge out of the system, keeping it at 4 rather than 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?

'Select exactly one initiative, several initiatives or all' gives the selection rules, and 'No import; no history backup' carves out what this tool is not for. It stops short of naming a concrete alternative (e.g. history or share) for the cases it excludes.

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 supply readOnlyHint=false, so the description carries most of the burden and does add real value: it discloses the cascade onto live incident edges and that history remains inspectable rather than destroyed. It is silent on permissions, whether the retraction can be undone, and how ambiguity in the node reference is handled (the schema hints 'ambiguity is an error' but the description does not reinforce the failure mode).

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 and target, with the cascade effect and history guarantee packed into the same clause. Nothing is redundant or padded.

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

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

An output schema exists, so return values need not be described, and the cascade-plus-history disclosure covers the core semantics of this mutation. For a tool with a required initiative scope and an expected_revision guard, though, the description leaves the agent without guidance on concurrency conflicts, ambiguous node resolution, or retry/idempotency 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?

Coverage is only 50% and the description adds no parameter meaning beyond the schema: it never mentions that 'initiative' scopes resolution, nor that 'expected_revision' is an optimistic-concurrency guard or that 'request_id' is a replay key. 'A record' loosely maps to the node parameter, but the concurrency and idempotency arguments — the ones most likely to be misused — go unexplained in both prose and 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 ('retract') and resource ('a record and its live incident edges') plus the net effect ('preserving inspectable history'), which disambiguates the odd name 'forget' from a hard delete. It does not, however, differentiate itself from nearby siblings such as lifecycle, retention, or replace, which plausibly overlap with record retraction.

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 lifecycle, retention, replace, or revise. 'Preserving inspectable history' weakly implies this is the soft-retraction path rather than a purge, but the agent must infer that; no exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail: fields whose prior values are not stored get labeled, so the agent knows partial history is possible. It says nothing about ordering, pagination via cursor, or what budget_chars truncation does.

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; the core verb and resource come first. It is terse to the point of under-specifying, but nothing is 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?

An output schema exists, so return values needn't be explained, and annotations cover read-only safety. However, for a tool with a nested NodeRef reference, cursor pagination, and a char budget, the description leaves all invocation mechanics and scoping 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?

Schema description coverage is reported at 0%, yet the description mentions none of the four parameters. 'cursor', 'budget_chars', and 'initiative' are undocumented in both places, so the agent must infer pagination and response-size control entirely from names and 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?

The description gives a specific verb and resource: 'Read recorded versions and audit events' for a node. It is clear what the tool returns, but it doesn't differentiate itself from vague-named siblings like 'trail', 'context', or 'read', so an agent must infer the boundary.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. An agent must guess whether to reach for this versus 'trail', 'context', or 'read' when inspecting an entity's past.

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 supply readOnlyHint=false, so the description carries the burden: it says 'every action has explicit scope and effects' without stating what merge or delete destroy, whether they are reversible, or that they require confirmation. It also omits the replay/idempotency contract that the schema's request_id points to, and says nothing about expected_slot_revision concurrency 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 short sentences with the action list front-loaded; nothing is padded. The closing sentence, 'Every action has explicit scope and effects', is vague boilerplate that asserts rather than informs.

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 six-variant mutation tool with destructive operations (merge, delete) and a concurrency token, the description omits irreversibility, permission/auth needs, and the replay contract, despite an output schema existing. An agent could call merge or delete without knowing the consequences.

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 oneOf variants already name every field (source/target, node, slot, expected_slot_revision). The description adds only the loose notion of a 'current-record slot' and otherwise paraphrases the action set the schema defines exactly.

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 specific verbs and resources: rename, merge, delete, attach membership, set/clear a slot. An agent immediately knows this is the mutating counterpart to the sibling 'initiatives' listing tool, though the description never names that 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?

No guidance on when to choose this over siblings such as 'initiatives' or 'lifecycle', no prerequisites, and no when-not conditions. 'Occasionally set/clear a current-record slot' hints at rarity but not at any selection criteria.

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

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

readOnlyHint=true already covers the safety profile, and the description adds two non-obvious behaviors: results are restricted to 'accessible' initiatives (visibility scoping) and filtering is side-effect-free with respect to aliases. It does not describe pagination behavior despite a cursor parameter, 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?

A single dense sentence with the primary operation front-loaded and the alias caveat appended; no filler or 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?

An output schema exists and annotations cover read-only safety, which lowers the burden. Still, for a paginated list tool with three undocumented parameters, the description omits pagination and result-size semantics 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 0%, so the description must carry all parameter meaning, but it only vaguely gestures at filtering. It says nothing about the 'filter' syntax, the 'cursor' pagination token, or what 'budget_chars' controls (a 512-64000 response-size budget is non-obvious).

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 ... initiative names') plus a scope qualifier ('accessible'), which lets an agent distinguish it from the mutating sibling initiative_manage and from cloud_initiatives. Lacks any explicit naming of those siblings, so it falls 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?

The word 'List' implies a read/retrieval use case, and the caveat 'filtering does not create or merge aliases' tells the agent this is not the path to alias management. However, it never states when to prefer this over initiative_manage or cloud_initiatives, nor any prerequisite.

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 readOnlyHint=false, so the description carries most of the burden. It does usefully disclose that content is retained and graph identity lineage is preserved, which tells the agent this is a reversible-tier move rather than a deletion. It says nothing about permissions, idempotency/replay behavior implied by request_id, or whether archived records disappear from default reads and searches.

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 action and the key preservation guarantee are stated up front. Its brevity is efficient but edges into under-specification for a 6-parameter mutation.

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 six parameters, a large sibling ecosystem containing near-neighbors (retention, forget, history), and an output schema, the description is thin. It omits what archiving actually does to the record's discoverability and links, whether the move is reversible, and any concurrency guidance around expected_revision.

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 only 33%, so the description needs to compensate, and it does not mention any parameter. Critically, it never explains the operational distinction between the two tiers (visibility, mutability, queryability), which is the single most important semantic for target_tier. Optional parameters like target_type and expected_revision are left 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?

The description states a concrete verb and resource: moving a record between 'operational' and 'archival' tiers, matching the target_tier enum. However, it calls the target a 'record' while the schema calls it a 'node' and enumerates 17 node types, and it never distinguishes itself from plausible siblings like 'retention', 'forget', or 'history'.

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 statement of when to use this tool versus alternatives such as retention, forget, or history. The phrase 'with full content and preserved graph identity lineage' hints that this is a non-destructive alternative to deletion, but the agent must infer that condition rather than being told it.

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

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

The annotation readOnlyHint=false already establishes that this is a mutation, and the description consistently says 'Create.' It adds the notion of a 'soft reference' but does not explain what that means operationally, whether duplicates are allowed, what permissions are required, or what side effects occur.

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 text. It is concise, though its brevity reflects under-specification rather than efficient completeness.

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-parameter mutation tool with no output schema, 0% schema description coverage, and only a minimal readOnlyHint annotation, one short sentence is not enough. It leaves required parameter semantics and creation behavior undocumented.

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 five parameters, and the description mentions none of them. It does not clarify required fields such as initiative, name, cloud_id, or the distinction between cloud and cloud_id, so it provides no parameter meaning beyond the bare 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: 'Create a soft reference to a cloud record.' This is more than a tautology, but 'soft reference' is domain jargon and the description does not distinguish this tool from siblings such as cloud_links, share, or reference.

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 no guidance on when to use this tool versus alternatives like cloud_links, share, or unshare. It only implies creation, with no prerequisites, exclusions, or routing context.

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

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

The readOnlyHint=false annotation already signals a write operation, and the description's 'Save' is consistent with that. However, it does not disclose important behavior such as slot conflict handling, idempotency/replay semantics, sharing implications, or what happens when the named slot already exists.

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

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

The description is two short sentences with no filler and is front-loaded with the core action. The second sentence adds a useful parameter hint, so 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?

Although an output schema exists and return values need not be described, the input schema is complex with 10 parameters and nested option objects. The description is far too sparse to prepare an agent to call the tool correctly, especially for slot revisions, sharing, reminders, applicability, and relation fields.

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

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

With 10 parameters and only 10% schema description coverage, the description is expected to compensate. It only explains the optional slot parameter as naming the current record for a project purpose, leaving initiative, body, kind, name, options, related, sharing, reminder, applicability, and request_id undocumented in the 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?

The description uses a clear verb, 'Save', and names the record types the tool handles: observation, decision, constraint, plan, or outcome. It does not differentiate the tool from siblings such as task_update, context, or reflect, so it falls short of the top score despite being understandable.

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

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

It states what can be saved but gives no guidance on when to choose this tool over alternatives, no prerequisites, and no exclusions. An agent must infer usage from the name and description 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?

Annotations declare only readOnlyHint=false, so the description usefully adds that pinning is about visibility, not role assignment or knowledge supersession. However, it omits important mutation behavior such as the conditional reason requirement when enabling a pin, revision-conflict handling via expected_revision, and whether pinning is reversible or idempotent.

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

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

The description is a single compact sentence that front-loads the core action and follows with a useful scope boundary. There is no wasted wording.

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 details are not required in the description. Still, for a six-parameter mutation tool with partial schema coverage and conditional requirements, the description leaves out behavioral details an agent would benefit from knowing before invoking 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 only 33%, and the description adds no parameter-level meaning. It does not explain initiative scoping, what enabled=true/false mean in context, why reason becomes required when enabling, or how expected_revision and request_id affect the operation.

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

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

The description states a specific action and resource: keeping a record in view or releasing the pin. It also clarifies what the tool does not do (assign a role or supersede other knowledge), which helps distinguish it from related knowledge-governance tools. It stops short of naming a sibling tool directly.

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 'keep a record in view or release the pin,' but there is no explicit guidance on when to choose pin versus alternatives such as note, reference, or claim. The negative boundary ('does not assign a role or supersede other knowledge') is useful but not a full when-to-use rule.

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

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

The readOnlyHint=false annotation already signals that this tool can mutate state. The description adds useful behavioral context by saying empty clouds explicitly removes the restriction and that policy and clouds can be set independently, but it does not cover permissions, side effects, or the concurrency behavior referenced by expected_revision.

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

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

The description is two short sentences with no wasted language, and the key read-or-set distinction is front-loaded. The empty-clouds caveat follows immediately where it is most useful.

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-parameter mutation tool with only partial schema coverage and sparse annotations, the description omits important context such as the required initiative target, concurrency via expected_revision, and replay semantics via request_id. An output schema exists, so return values need not be described, but the invocation behavior is still under-specified.

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 only 40%, so the description needs to compensate for several parameters. It clarifies the empty-array behavior for clouds and implies policy values are independent, but does not explain initiative, request_id, or expected_revision, leaving much of the parameter semantics 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?

The description states a specific dual action, 'Read or set', on specific resources, 'sharing policy and allowed clouds'. It is clear what the tool operates on, though it does not explicitly differentiate itself from siblings such as share, unshare, or clouds.

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 says the tool can read or set policy and clouds independently, but gives no explicit guidance on when to choose this tool versus share, unshare, or clouds. Usage is implied rather than directed, with no exclusions or alternatives named.

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

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

The description is consistent with readOnlyHint=false because it describes a copy into the local initiative, which implies mutation. However, it does not disclose important behavioral details such as whether an existing local node is overwritten, what permissions are required, or whether the operation is idempotent.

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

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

The description is a single front-loaded sentence with no wasted words. Its brevity is appropriate structurally, though it contributes to the surrounding completeness gaps.

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

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

For a 3-parameter mutation tool with no output schema and minimal annotation detail, the description is too thin. It identifies the broad action but omits parameter semantics, side effects, and selection guidance among many related cloud and link 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 description coverage is 0%, so the description must carry parameter meaning. It hints that 'id' identifies the cloud node and 'initiative' is the local target, but the optional 'cloud' parameter is completely unexplained, and no format or default information is provided.

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: 'Copy one cloud node into the local initiative.' It clearly distinguishes a copy action from a link action, but it does not explicitly differentiate itself from close siblings such as cloud_recall, link_cloud, or sync_review.

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

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

The description gives no when-to-use guidance, prerequisites, or alternatives. It implies a copy operation but does not tell the agent when to choose this over related tools like link_cloud or cloud_recall.

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

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

Beyond the readOnlyHint annotation, the description discloses what is returned by default and that named graph views can be expanded. It does not mention pagination, budget behavior, or error conditions, but the output schema and annotation reduce the burden.

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

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

The description is a single front-loaded sentence with no filler, stating default behavior before optional expansion. Every clause earns its place.

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

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

For a complex tool with 8 parameters, conditional schema constraints, and missing parameter descriptions, this one-sentence description is not sufficient. The output schema covers return values, but the input semantics and usage context remain largely undocumented.

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

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

With 8 parameters and 0% schema description coverage, the description only hints at 'record' (node) and 'named graph views' (likely include). It leaves initiative, cursor, to, edge_types, recorded_at, and budget_chars 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 gives a concrete verb-resource pair ('Read a record') and specifies the default payload (currentness, material doubts, saved reasoning summary) plus optional expansion of named graph views. It does not explicitly differentiate itself from sibling tools such as search or context, so it falls short of a 5.

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

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

It implies default usage and conditional expansion ('when needed'), but gives no explicit guidance on when to use this tool versus search/context alternatives. Usage is only implied rather than clearly stated.

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

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

Annotations declare readOnlyHint=false, and the description correctly implies a write operation by saying it preserves content. It adds one useful behavior: a URL alone records a citation without fetching it. However, it omits major mutation semantics exposed in the schema, including slot replacement, layer placement, expected_slot_revision concurrency checks, relation creation, and sharing visibility.

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

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

The description is a single front-loaded sentence using a semicolon to attach one key caveat. There is no filler; every clause carries either purpose or behavior.

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 9-parameter write tool with a complex schema and no output explanation needed, the description is far too thin. It covers source content and the URL caveat but leaves slot/layer semantics, concurrency control, relations, and sharing behavior unexplained, which is a significant gap for an agent invoking this tool correctly.

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

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

Schema description coverage is only 11%, so the description must compensate. It adds meaning for the 'source' choice (text vs artifact) and the URL-only case, but it says nothing about required parameters like initiative and name or about options, related, sharing, request_id, and description. Most parameter semantics are left 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?

The description uses a specific verb ('Preserve') and names the resources it stores: supplied source text or a verified artifact. It also distinguishes a URL-only call from a fetch. It does not explicitly contrast itself with siblings like note, pin, or context, so it falls 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 when-to-use guidance and no named alternative among the many sibling tools. The only routing hint is that a URL alone records a citation without fetching it, which clarifies one edge case but not general tool selection.

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

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

readOnlyHint already covers the safety profile; the description adds that it performs no automatic semantic edits, which usefully confirms it only reports candidates rather than applying fixes. It still omits whether repeated calls are cheap, whether results are paginated, and whether anything is cached or persisted.

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; every clause names a category of diagnostic output or a non-mutation guarantee. It is terse but not padded.

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

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

Because an output schema exists, return shape need not be described, and readOnlyHint covers safety. However, the required initiative parameter and the include/cursor/budget_chars controls are unexplained, so an agent lacks enough information to scope and page the call 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 0% for four parameters, and the description documents none of them by name: initiative, include, cursor, and budget_chars all lack semantic explanation. The listed findings loosely correspond to include enum values, but that mapping is not stated, so the description does not 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?

The description states a read-only diagnostic operation and enumerates four concrete findings it surfaces: unresolved work, stale summaries, scope fragmentation, and maintenance candidates. It is clearer than the bare name reflect, but it never distinguishes itself from siblings such as context, review, or trail, so an agent must infer the boundary.

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

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

There is no explicit when-to-use guidance and no named alternatives. The closest signal is the trailing 'no automatic semantic edits,' which implies inspection-only use, but the agent is left to infer when reflect is preferable to context, review, or trail.

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

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

The annotation only declares readOnlyHint=false, so the schema and description carry the rest. The description usefully discloses non-obvious graph semantics — a supersedes edge records succession without retracting the node — but says nothing about the replay/idempotency contract (request_id), the optimistic-concurrency requirement (expected_revision), or whether disconnect is reversible.

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 operation set, and the second sentence carries a genuinely non-obvious caveat. No filler and nothing redundant with the schema.

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

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

An output schema exists and the input schema is richly annotated, so the description needn't restate parameters. Still, for a mutation tool spanning three actions it omits the failure modes (ambiguous NodeRef is described only in the schema) and the concurrency/replay behavior an agent must plan around.

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 effectively complete: actions, weight bounds, NodeRef resolution rules, cloud mirroring, and expected_revision are all documented inline. The description clarifies the meaning of one enum value (supersedes) but adds nothing for the other eleven edge types or the three actions.

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 specific verbs (connect, disconnect, reweight) against a specific resource (typed directed edge), which is far more informative than the bare name 'relate'. It does not distinguish itself from siblings such as 'reference' or 'link_cloud', so sibling disambiguation is left 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?

There is no statement of when to use this tool versus 'reference', 'link_cloud', 'share', or 'replace', nor any mention of preconditions. The only guidance-like sentence is a semantic footnote about the supersedes edge type, not a usage rule.

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

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

Annotations only declare readOnlyHint=false; the description adds meaningful behavior by stating the operation is atomic and reports dependents needing review. It stops short of saying whether the old record is deleted or retained, what permissions are needed, or whether the replacement is reversible.

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. Each clause earns its place by conveying successor creation, atomic supersession, and dependent reporting.

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

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

The output schema exists, so return-format details are not required in the description. However, for a multi-parameter mutation tool with low schema coverage, the description omits concurrency semantics, parameter usage, and guidance versus alternatives, leaving gaps 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 only 40%, and the description does not explain the parameters beyond referring conceptually to an 'old record' and 'successor'. It leaves initiative, expected_revision, and request_id without added meaning, failing to compensate for the schema gaps.

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

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

The description uses specific verbs ('create', 'supersede') and resources ('old record', 'explicit successor'), making the replacement operation clear. It does not explicitly name sibling alternatives like revise, but the core purpose is distinguishable from an in-place edit.

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

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

The description implies use when replacing a record with a new successor, but gives no explicit when-to-use/when-not guidance versus siblings such as revise, task_update, or review. No prerequisites or exclusions are stated.

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

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

With only readOnlyHint=false, the description carries most of the burden for a mixed read/write tool, yet it never says whether run_hygiene deletes or rewrites metadata, whether set_layer can move data into an irrecoverable 'frozen' state, or what the request_id/expected_revision concurrency contract implies. The phrase 'tier and semantic closure remain explicit' is unexplained jargon rather than behavioral disclosure.

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

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

It is a single short sentence with the operational gist front-loaded, which is good. However, the trailing clause about 'tier and semantic closure' consumes space without conveying actionable meaning, so not 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?

An output schema exists, so return values needn't be explained, but for a three-variant tool that includes mutations, the definition leaves out what hygiene actually does, what a layer change costs, and any safety prerequisites. The complexity of the oneOf schema is not matched by the description's depth.

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 parameter meaning is already carried by the schema (NodeRef, Layer enum, budget_chars, request_id, expected_revision). The description adds nothing beyond the word 'tier', 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?

The description names three loosely-coupled capabilities — setting a 'recall layer', and inspecting/running 'metadata hygiene' — but the vocabulary ('recall layer', 'tier and semantic closure remain explicit') is idiosyncratic and never grounded in the layer enum or the set_layer/preview_hygiene/run_hygiene actions the schema actually exposes. An agent can guess it's about retention policy, but cannot confidently map the description to what each action does.

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

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

There is no guidance on when to use this tool versus siblings like forget, lifecycle, pin, or reflect, nor on how to choose among the three actions. 'Inspect' vs 'run' hints that preview_hygiene is the safe read and run_hygiene the mutation, but no exclusion or prerequisite is stated.

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

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

Annotations already indicate this is a mutating tool via readOnlyHint=false. The description adds a valuable behavioral nuance: closing flags does not delete substantive counterevidence. It does not cover authorization or side effects in more depth, but with annotations present this is solid context.

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 possible actions and followed by a key behavioral caveat. There is no redundant or wasted text.

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

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

The tool has a rich oneOf schema and an output schema, reducing what the description must carry. The description adequately names all three actions and one important side-effect nuance, though it could say more about the distinction between opening and closing flags.

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 fields like request_id and expected_revision in detail. The description restates the three action modes but adds little parameter-level meaning beyond the schema baseline.

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

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

The description uses specific verbs and resources: opening/closing review flags and linking an answer to a question. It clearly covers the three action modes, though it does not explicitly distinguish this tool from related siblings such as sync_review.

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 action list implies when the tool is used, but there is no explicit guidance on choosing between open, close, and answer, nor when to prefer this tool over sibling review-related operations. Usage is inferable but not spelled out.

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 readOnlyHint=false, so the description usefully adds mutation semantics: identity and tier are preserved, omitted fields are untouched, and immutable bytes require replace. It still omits concurrency behavior (expected_revision) and failure modes when immutable bytes are patched.

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

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

Two sentences, no filler, and the replace distinction is front-loaded. The terseness comes at the cost of clarity around 'the same record', but structurally it is efficient.

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

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

For a mutation tool with five parameters, nested patch fields, and only a readOnlyHint=false annotation, the description is too thin. It leaves out targeting (initiative/node), concurrency (expected_revision), and error behavior for immutable bytes, even though an 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 40% across five parameters. The phrase about omitted fields adds meaning for the patch object, but the description never explains initiative, node, expected_revision, or request_id, so it does not 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 uses a specific verb ('Patch') and distinguishes itself from replace by noting immutable source bytes are handled elsewhere. However, the resource is vague ('the same record'), and it never states that the target is an initiative node. An agent can infer a partial-update operation but not the exact domain object.

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 provides an implicit alternative: immutable source bytes must go through replace. That is useful routing guidance. It does not say when to prefer revise over task_update or other mutation siblings, so usage is only partially implied.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that search is literal-text based rather than semantic and that results report currentness and matched scopes, which is useful behavioral context, but it omits pagination, truncation via budget_chars, and how 'current' defaults affect results.

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

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

A single front-loaded sentence with no filler. The two clauses separate the search mode from output behavior, though the second clause is somewhat compressed and could be clearer.

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

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

The output schema is present, so return values need not be explained, and readOnly is covered by annotations. But for an 8-parameter tool with complex anyOf requirements and 0% schema descriptions, the description is too thin to guide correct invocation, especially around cursor/limit and budget_chars truncation.

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 8 parameters, so the description must compensate and it largely does not. It loosely maps to text, filters, initiatives, and currentness, but leaves limit, match, cursor, prefix, and budget_chars unexplained, making it hard to invoke non-trivially without inspecting 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 gives a specific verb and resource: 'Find scoped memory' and names the two modes, literal text or explicit filters. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as read, context, or trail.

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 'using literal text or explicit filters' implies the two valid search modes and the required initiative scoping is hinted by 'scoped memory'. However, there is no explicit guidance on when to use this instead of sibling tools, no exclusions, and no explanation of when to prefer text vs filters.

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

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

The annotation already declares readOnlyHint=false, indicating a mutation. The description adds only that sharing requires "existing sharing gates", but it does not explain what those gates are, what permissions are needed, whether sharing is reversible, or what the "force" flag changes. For a mutation tool with minimal annotations, this leaves 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?

The single sentence is technically concise but suffers from under-specification rather than efficient communication. "Sharing gates" is unexplained and the sentence wastes the only opportunity to tell the agent what the tool actually does and requires.

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 four parameters (two required), zero schema descriptions, no output schema, and only a readOnly=false annotation, the description is far too thin. It does not cover the required initiative/name inputs, the meaning of cloud or force, or the expected outcome, leaving the agent unable to invoke the tool reliably.

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, but it does not mention any of the four parameters. The required "initiative" and "name" fields, as well as "cloud" and "force", are left completely 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 ("Share") and resource ("node"), but the phrase "using existing sharing gates" is jargon that does not clarify scope. It also does not distinguish this tool from the sibling "unshare" or "link_cloud", leaving the agent to infer the difference.

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

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

There is no guidance on when to use this tool versus alternatives such as "unshare" or "link_cloud", nor any prerequisites or exclusions. The agent must guess the appropriate context from the name 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?

readOnlyHint=true is consistent with "List", so no contradiction. The description usefully adds the "local" scope (as opposed to cloud-oriented siblings) and that results are constrained by existing policy, but it says nothing about volume, pagination, or what a candidate record looks like beyond the implied scope.

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

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

A single tight sentence with the scope front-loaded and no filler. It is efficient, though the brevity edges toward under-specification rather than deliberate concision.

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

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

No output schema exists, so the description should explain what a "sharing candidate" is and what the initiative parameter selects; it does neither. Combined with the mismatch between the name and the described behavior, an agent lacks what it needs to call this 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?

There is one required parameter, initiative, with 0% schema description coverage, and the description never mentions it. An agent must guess whether initiative is a name, an ID, or a scope selector, so the description 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?

The description has a specific verb and object ("List local sharing candidates") plus a scoping phrase ("under existing policy"), which is more than a tautology. But it does not reconcile with the tool name sync_review, and it never distinguishes this listing from siblings such as share, policy, or review, leaving an agent unsure whether this enumerates or triggers anything.

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, when-not-to-use, or prerequisite guidance is given. With siblings like share, unshare, policy, and cloud_links in the namespace, the description offers no routing signal about when an agent should pick sync_review over any of them.

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

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

The readOnlyHint=false annotation already signals a mutation, and the description adds a non-obvious behavioral guarantee: it does not silently close or retire the sources. That is useful side-effect context beyond the annotation. It still omits permissions, replay/idempotency behavior, and any mention of the request_id replay contract, but the source-retention clause is meaningful additional transparency.

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

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

The description is a single front-loaded sentence with no filler, and the semicolon cleanly separates the core action from the source-handling caveat. Every clause earns its place.

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

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

For a mutation tool with four parameters, nested NodeRef definitions, and an output schema, the description is too thin. It covers the core operation and one side effect, but leaves initiative, request_id/replay, NodeRef targeting, and usage relative to siblings unexplained. The output schema reduces the need to describe return values, but not the missing invocation context.

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 only 25%, so the description would need to compensate by explaining the four parameters. It only loosely maps 'supplied synthesis' to result and 'links to its sources' to sources, while saying nothing about initiative, request_id, the NodeRef forms, or the tier/type fields. The low coverage leaves significant parameter semantics 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 and resource: create a synthesis with links to its sources. That is clear enough to understand the core operation. However, it does not distinguish the tool from nearby siblings such as note, reference, or relate, so an agent cannot tell from the description alone when 'synthesis' is the right artifact.

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 the tool does but gives no guidance on when to use it instead of note, reference, relate, or other creation tools. It also provides no prerequisites, exclusions, or context about which situations call for a synthesis.

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 supply only readOnlyHint=false, so the description carries the burden of behavioral disclosure for a write tool. 'Open task' mildly communicates initial state and 'captured with it' hints at persistence, but nothing explains initiative scoping, the replay/idempotency contract behind request_id, or slot-revision conflict behavior in options.

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

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

One short sentence, front-loaded with the core action and scoped additions after the semicolon. Nothing is padded, though the brevity is partly under-specification rather than deliberate economy.

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, but the input side is complex: a oneOf NodeRef, a typed/weighted Relation, and a CaptureOptions object with optimistic concurrency fields. None of this complexity is acknowledged, leaving the agent to reverse-engineer required fields and conflict semantics from the schema.

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

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

Schema description coverage is only 17% across 6 parameters, and the description covers just two of them (due as 'deadline', related as 'relation') without format or semantics. It says nothing about the required initiative and body, nor about options or request_id, so it 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?

States a clear verb (Create) and resource (task) plus the resulting state ('open'), which is more than the bare tool name gives. It does not differentiate itself from the sibling task_update, so an agent must infer the create-vs-modify split from names 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?

The description gives no explicit when-to-use guidance and never names task_update or any other sibling as the alternative. The only usage signal is the implied create semantics of 'Create an open task'.

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 readOnlyHint=false, so the description carries the behavioral burden and does add real domain context: completing preserves the deadline and stops active debt accrual, reopening reuses the retained date. That is genuine side-effect disclosure an agent could not get from the schema. It omits other important traits: concurrency behavior via `expected_revision`, idempotent replay via `request_id`, and what happens on a stale revision.

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, and the primary purpose is front-loaded before the lifecycle caveats. The second sentence is dense but every clause (preserve deadline, stop debt, retained date on reopen) adds 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 values need not be described, and the read-modify-write lifecycle is partially covered. However, for a mutation tool with an `anyOf` schema (status-or-due), a free-form status string, and optimistic-concurrency parameters, the description leaves the agent without valid status values or guidance on supplying `expected_revision` — material gaps 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 only 33%, so the description must compensate, but it explains only that `status` and `due` are the target fields. Critically, `status` has no enum and is a bare string, and the description never lists valid status values; it also does not say that a null `due` clears the deadline, nor explain `expected_revision` or `request_id` at the call site (the schema only references a 'replay contract').

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 and resource ("Update task status or deadline") and identifies the two mutable fields, so the agent knows exactly what class of change this performs. It does not differentiate itself from similarly named siblings such as `task`, `revise`, or `replace`, leaving the agent to infer that those are for content edits and this is for status/date edits.

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 statement of when to use this tool versus `task` (read/other), `revise`, or `replace`, and no prerequisites or exclusions are given. Usage is only implied by the phrase "status or deadline", which is a weak router when 30+ siblings exist.

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

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

The annotation declares readOnlyHint=false, and the description is consistent by describing save, refresh, and extend operations. It adds useful context about summary staleness being exposed, but does not disclose concurrency behavior, required permissions, or what happens to existing route data.

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

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

The definition is a single dense sentence with the primary save behavior front-loaded. It is efficient, though the semicolon-separated action summary is somewhat compressed.

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

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

The tool has a complex oneOf schema and an output schema, so the description does not need to explain return values. Still, for a mutation tool with save/refresh/extend variants, the description is minimal about revision checks, replay keys, and the practical meaning of summary staleness.

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 parameters such as expected_revision and request_id. The description adds only action-level context and does not explain route structure, NodeRef resolution, or revision semantics beyond what the schema provides.

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

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

The description states a specific resource and multiple operations: saving a reasoning summary plus ordered route, and refreshing or extending an existing trail. It clearly conveys what the tool does, though it does not distinguish itself from any of the many sibling tools.

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

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

It implies usage through the save/refresh/extend actions and says refresh or extend applies to an existing trail. However, it gives no explicit when-to-use guidance relative to siblings and no when-not-to-use or prerequisite information.

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

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

The description is consistent with readOnlyHint=false, but adds nothing beyond it: no statement of whether the withdrawal is reversible, what happens to the node's other associations, whether permissions are required, or what an error looks like. For a mutation exposed with a single annotation hint, this is a substantial 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?

It is a single short sentence with no padding, but the brevity is under-specification rather than economy: there is nothing front-loaded beyond a bare verb phrase, and no second clause carries the needed detail.

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

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

A mutating tool with three parameters at 0% schema coverage, no output schema, and only a readOnlyHint=false annotation requires far more than one sentence. Nothing tells the agent what a correct call looks like or what the effect is.

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 all three parameters are undocumented. The phrase "named cloud" hints at `cloud`, but that parameter is optional while the description reads as though it is essential, and the required `initiative` parameter is never mentioned at all — an agent has no basis for supplying it.

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

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

States a specific verb ("withdraw") and resource ("node from the named cloud"), so the general intent is inferrable. However, "node" is never defined, and the description never contrasts with the obvious inverse sibling `share`, so an agent cannot confidently distinguish the two from the text 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?

No guidance on when to use this versus `share`, `cloud_links`, or `link_cloud`, and no prerequisites or preconditions are stated. The inverse relationship to the `share` sibling 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?

Annotations only declare readOnlyHint=false; the description adds real value by disclosing that status plus optional evidence can be written atomically in one call, and that record_check leaves status untouched. It still omits mutation-side behavior an agent would care about: whether an existing verdict is overwritten, how expected_revision conflicts surface, and how ambiguous NodeRef resolution errors behave.

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

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

Two sentences, no filler, and the core operation is front-loaded before the exception branch. Every sentence contributes a distinct fact.

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 two action branches are covered. But for a non-read-only mutation on a hypothesis node, the description says nothing about concurrency handling, overwrite semantics or initiative scope, which are the likely failure modes an agent needs to know.

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 $defs document NodeRef, Verdict and Evidence in detail, so the schema carries most of the load. The description adds only marginal semantics - that evidence is optional in the default branch - leaving expected_revision and request_id entirely to the schema text.

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 pairs a specific verb ('Record') with the exact resource domain (supported/refuted/inconclusive verdicts) and mentions the second action variant 'record_check', so an agent knows this tool sets a hypothesis verdict. It does not distinguish itself from siblings such as claim, revise or review, leaving some ambiguity about which node-mutating tool to pick.

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 rare record_check action attaches evidence without changing status' gives a usable cue for choosing the non-default branch over the default 'decide'. However, there is no guidance on prerequisites (initiative scoping, when a verdict should be issued versus revised later) or on when to prefer siblings like revise or review.

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