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

Annotations already cover safety and idempotence, but the description adds meaningful operational context: retries are safe for 30 days on the same local Ygdria database and expectedVersion can be used. It stops short of explaining failure behavior or what happens after the 30-day idempotency window.

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

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

Three short sentences, front-loaded with the core action and followed by the important idempotency and version constraints. There is no wasted language.

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

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

For a mutation tool with no output schema, the description covers the essential append, retry, and version-check behavior. It could be more complete by mentioning error cases or what the response contains, but the annotations reduce the need for safety disclosure.

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 0% schema description coverage, the description helps by explaining that idempotencyKey is required for retry safety, expectedVersion is optional, and text contains Markdown blocks or literal code. However, noteId is only indirectly implied by 'latest note,' and the semantics of expectedVersion remain vague.

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 ('Append Markdown blocks') plus the key scope constraint ('without replacing existing content'), which clearly distinguishes it from sibling replacement tools like replace_content or replace_section.

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 contrast with replacement behavior gives clear usage context, and the required idempotencyKey signals retry-oriented use. It does not explicitly name alternatives or say when not to use this tool, so it falls short of a 5.

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

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

Beyond the annotations, the description discloses the idempotency contract: a unique key, same-key-same-params retry semantics, and a 30-day window — information an agent could not derive from idempotentHint=false alone. It does not say what is returned or whether missing optional fields default silently, but the idempotency disclosure is substantive added value.

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

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

Two tight sentences with the operation front-loaded and the retry contract second; nothing is redundant. The clause 'including necessary notes for organizing or summarizing' is filler that could be cut without loss.

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

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

This is a mutation tool with no output schema, no annotations covering permissions or side effects, and 0% schema coverage on six parameters. The description covers the idempotency story well but leaves the agent guessing about required inputs, field defaults, placement behavior, and what a successful create returns.

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

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

Schema description coverage is 0% across 6 parameters, yet the description only explains idempotencyKey. It says nothing about title (the sole required field), content, tags, the text/code enum on type, or parentPlacementId — so the agent gets no help on five undocumented parameters.

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

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

The description gives a clear verb+resource ('Create a note') and scopes it to 'the user-authorized task', which distinguishes it from update_note, edit_content, append_content and the search_* siblings. The phrase 'including necessary notes for organizing or summarizing' is slightly muddy but the core operation is unambiguous.

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

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

The retry condition is spelled out precisely (uncertain network result → retry with the same key and identical parameters within 30 days), which is genuine when-to-use guidance. However, nothing tells the agent when to pick this over append_content, edit_content or update_note, nor what prerequisites (auth, parent placement) must hold.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds the semantics behind that — edits are atomic, targets must match exactly, and dryRun exists as a safe preview. It omits failure-mode detail (what happens when a match count differs from expectedMatches or version is stale), which would complete the picture.

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, zero filler, with the core mechanism front-loaded and the preview option trailing. Every clause carries information an agent needs.

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

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

For a destructive, non-idempotent mutation with no output schema and 40% schema coverage, the description covers mechanism and preview but not concurrency (expectedVersion), match-ambiguity resolution, or what the caller gets back. Adequate to invoke, not complete enough to invoke confidently.

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

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

Schema coverage is 40%; the description covers oldText/newText and clarifies dryRun's purpose beyond its bare default. It says nothing about noteId, expectedVersion/version conflict handling, or expectedMatches, leaving half the parameters reliant on thin 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?

States a specific verb and mechanism: 'atomic literal oldText/newText edits' to a note. It implicitly distinguishes itself from whole-content siblings (replace_content, append_content, replace_section) by emphasizing literal find/replace, but never names them, so the agent must infer the boundary.

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

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

Gives a prerequisite ('read earlier with get_note') and a preview path ('use dryRun to preview'), which is real guidance. It does not state when to choose this over replace_content or replace_section, nor when dryRun is mandatory before a destructive edit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a non-obvious behavioral trait: the response carries a version that must be retained for subsequent writes, and that version may alternatively come from a note resource or a prior write response — useful concurrency context beyond structured 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?

Three short sentences, front-loaded with the core action and with zero filler. The final sentence about version sourcing is terse to the point of being slightly cryptic, but nothing is padded.

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

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

For a simple two-parameter read with annotations covering the safety profile and no output schema, the description is adequate on the write-after-read workflow. It leaves real gaps on the format options and on what the returned note representation contains, which the agent would have to discover by calling.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never mentions the `format` parameter or its markdown/json/html enum and default. The only semantic content it adds ("version") is a return value, not an input, so the parameters remain 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?

States a specific verb and resource ("Read a note through ETAPI"), so the agent knows this is a single-note fetch. It does not distinguish itself from plural siblings like get_notes or section-scoped reads like get_section, but the core action is unambiguous.

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

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

"Read current content before replacing existing text" implies the read-before-write pattern relative to replace_content/edit_content, which is genuine usage context. However, no alternative is named explicitly (get_notes, get_section) and no exclusion conditions are given, so the agent must infer routing.

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

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

Annotations already declare a safe read operation, and the description adds useful behavior beyond them: batch size, per-note results, byte-budget deferral of remaining IDs, and protected-note inaccessibility. It could say more about partial results or error behavior, but it meaningfully improves 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?

Two compact sentences with no filler. The core action is front-loaded, followed by the view choice, byte-budget behavior, and protected-note caveat.

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

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

For a read-only batch tool with annotations covering safety and no output schema, the description gives enough operational context to call it correctly. The main omission is excerptLength semantics and some return-shape detail, but the overall behavior is adequately 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%, so the description must carry parameter meaning. It explains the view choices and the maxBytes deferral behavior, and 'up to 50 notes' maps to noteIds limits, but excerptLength is not addressed at all and noteIds/defaults are not explicitly described.

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

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

States a specific verb and resource ('Read ... notes') and adds batch scope ('up to 50 notes with per-note results'), which distinguishes it from the single-note sibling get_note. It does not explicitly name get_note or search_notes as alternatives, so sibling differentiation is implied rather than stated.

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 usage for fetching multiple known note IDs and explains the view and byte-budget options, but it does not explicitly say when to use get_notes instead of get_note or search_notes. The only exclusion is that protected notes remain inaccessible.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior the schema can't convey: the response carries a current version, and the content must be forwarded verbatim to replace_section, implying version-staleness matters. It omits failure behavior for a missing or non-unique heading.

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 core purpose is front-loaded before the usage hint and parameter note. Every clause carries information the agent could not get from structured fields.

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, and the description compensates by naming what is returned (body plus current version) and how to chain it into replace_section. For a two-parameter read tool with read-only annotations, this is sufficient for correct invocation.

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

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

Schema coverage is 0%, so the description carries the load, and it explains the non-obvious parameter well: headingPath 'lists ancestor titles and the target heading,' which is essential given the schema only says it's a string array. noteId is left to the obvious interpretation, and no format details (e.g., whether titles are case-sensitive or matched exactly) are given.

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

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

States a specific verb and resource: 'Read a unique heading section body and current version.' The word 'unique' plus the headingPath note makes clear this resolves one section, which distinguishes it from get_note (whole note) and search_notes. Sibling differentiation is implied through the replace_section reference rather than stated as an explicit contrast.

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

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

Gives a clear read-then-write workflow: 'Pass the returned content unchanged as oldText to replace_section,' which tells the agent exactly when this tool is the prerequisite for a sibling. It does not state when to prefer get_note or search_notes instead, or what happens if the heading path is ambiguous.

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 and openWorldHint=false already declare the safety profile, so the description's added value should be error behavior, archived-node handling, or payload shape. It only offers 'compact metadata', with no statement about what is omitted, what happens for an unknown placementId, or how includeArchived changes 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 efficient, front-loaded sentence with no filler. It is short because it is under-specified rather than because it is tightly written.

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

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

With no output schema, the description should indicate what 'compact metadata' returns and must compensate for the undocumented parameters. It does neither, leaving the includeArchived flag and the return shape entirely opaque.

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%: neither placementId nor includeArchived has a description in the schema, and the description never mentions includeArchived or what its default of false means for archived nodes. 'Exactly one placement node' only faintly implies the single ID parameter.

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

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

States a specific verb (read) and resource (compact metadata for one placement node), and 'exactly one' implicitly distinguishes it from list_tree_children and get_tree_subtree. However, it never names a sibling or clarifies what a 'placement node' is relative to notes/sections handled by get_note or get_section.

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 list_tree_children, get_tree_subtree, get_tree_overview, or get_note. The agent must infer the choice 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?

Annotations only declare readOnlyHint and openWorldHint=false; the description adds real behavior: four independent budgets, the fact that the byte budget excludes continuation data, and that truncation surfaces depth-limited nodes separately. It still doesn't say what happens to omitted placementId (implied roots) or how includeArchived interacts with traversal.

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

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

Three tight sentences, front-loaded with the traversal scope before the mechanics. The jargon ("item-byte", "additional bounded navigation data") is dense but each sentence carries distinct information.

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

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

For a 7-parameter tool with a nested continuation object and no output schema, the description covers budget/pagination semantics but omits the archived-node flag, the roots-vs-placement default, and what a returned item looks like. Adequate but with clear gaps.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It maps conceptually onto maxNodes, maxDepth, maxBytes, maxRequests and continuation, but leaves includeArchived and placementId (roots-when-absent) unexplained, and does not clarify the nested continuation payload's fields.

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 (bounded recursive traversal of roots or a placement's descendants) and the resource (tree nodes). It is clear about scope and budget-limited expansion, but never names or distinguishes itself from siblings like get_tree_subtree, list_tree_children, or list_tree_roots.

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 operational guidance for continuing a traversal ("Pass returned continuation to continue") and notes that depth-limited nodes are listed separately. However, there is no guidance on when to prefer this over the several overlapping subtree/children/roots tools, leaving selection 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context by saying the read is bounded by explicit depth and node limits and a response budget, though it does not explain truncation behavior when maxNodes is reached.

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

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

The definition is a single, front-loaded sentence with no wasted wording. It states the core operation, its bounds, and the alternative tool in one compact structure.

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 subtree tool, the description covers the core action, limits, and the main sibling alternative, while annotations cover the safety profile. The remaining gaps, especially includeArchived semantics and truncation/return behavior with no output schema, are minor but still present.

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 description maps 'one placement' to placementId and 'depth and node limits' to maxDepth/maxNodes. But schema description coverage is 0%, and includeArchived is not explained at all, so the description only partially compensates for the missing parameter documentation.

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

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

The description states a specific verb and resource: read one placement and its descendants. It also sets the scope with explicit depth and node limits and names get_tree_overview as the cross-root alternative, so the agent can distinguish this from the overview tool without opening schemas.

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

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

It gives a clear condition for this tool, reading a single placement subtree within depth/node limits, and explicitly routes cross-root exploration to get_tree_overview. However, it does not distinguish this tool from closely related siblings such as get_tree_node or list_tree_children.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds the useful signal that the result is the complete tag set ('all tags'), but says nothing about ordering, whether tag hierarchy or usage counts are included, or how empty results appear.

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, appropriately sized for a zero-parameter read. The trailing 'through Ygdria ETAPI' is mild jargon that adds little for an agent.

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 parameterless read with annotations covering safety and no output schema, the description supplies enough to call it correctly. Only the shape of returned tag data is left unstated, which is a minor gap at this complexity.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The empty schema is consistent with the description's claim that all tags are returned unconditionally.

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 all tags') with the source system named, so an agent knows it enumerates the tag vocabulary rather than retrieving notes. It does not explicitly differentiate itself from the nearby 'search_by_tag' or 'update_tags' siblings, so an agent must infer the distinction.

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 the alternatives in the sibling set, nor any prerequisites or exclusions. Usage is only implied by the phrase 'list all tags.'

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 and openWorldHint annotations already communicate that this is a safe, closed read operation. The description adds that results are paginated and hints at using hasChildren for expansion decisions, but it does not explain pagination mechanics, cursor behavior, or archived-item handling.

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 the core operation front-loaded. Every sentence contributes either scope or traversal guidance, with no filler.

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

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

There is no output schema and no parameter description coverage, so the description should carry more context. It mentions hasChildren as if it is returned, but does not document the return shape, pagination fields, or what includeArchived changes.

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

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

Schema description coverage is 0%, so the description must compensate for four undocumented parameters. It only implies pagination via 'paginated' and hierarchy via 'direct child placement nodes,' leaving placementId, limit, cursor, and includeArchived 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 specific verb and resource: 'List direct child placement nodes.' The word 'direct' helps distinguish it from subtree-oriented siblings such as get_tree_subtree, but it does not explicitly name alternatives or state boundaries versus those 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?

The sentence 'Use hasChildren to decide whether further expansion is useful' provides traversal guidance, but it does not say when to choose this tool over list_tree_roots, get_tree_node, or get_tree_subtree. Usage is implied rather than explicitly scoped.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds 'paginated', which is genuinely extra behavioral context, but it says nothing about archived-node handling or what a page contains. Creditable but thin beyond annotations.

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

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

Two sentences, front-loaded with the scope constraint, zero filler. Nothing could be removed without losing routing information.

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

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

No output schema and no annotation gap, but the undocumented default of excluding archived nodes and the return shape of a page are never addressed. Adequate to invoke safely, not complete enough to predict results.

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 all three parameters, so the description carries the burden and mentions only pagination in passing. It never explains limit (default 50, max 100), cursor semantics, or what includeArchived=false means — the one param with real behavioral consequence.

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

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

Specific verb-plus-resource ('List ... top-level tree nodes') with an explicit scope qualifier ('only top-level') that separates it from list_tree_children and get_tree_subtree. The 'tree nodes' resource is slightly abstract given generic naming, but an agent can identify the operation without opening the schema.

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

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

Names two alternatives (resolve_tree_nodes for direct lookup, get_tree_overview for a budgeted overview) and gives the condition that selects each. The 'only top-level' scope phrase implicitly excludes the child/subtree traversal siblings, leaving nothing important to inference.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, and openWorld=false, so the safety profile is covered. The description adds no behavioral detail beyond 'move': it does not state whether descendants move with the node, how cycles are prevented, 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?

The description is two short sentences, front-loaded with the action and then the key identifier clarification. There is no filler or repetition.

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

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

For a three-parameter tree mutation with no output schema and no schema parameter descriptions, the definition is too thin. An agent still lacks guidance on destination placement semantics, position meaning, subtree behavior, cycle/error handling, and how this differs from the plural move_placements sibling.

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

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

Schema description coverage is 0% for all three required parameters. The description clarifies only that placementId, not noteId, identifies the moved item; it says nothing about parentPlacementId or position, leaving two of three parameters with no semantic explanation beyond their names and types.

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 and resource: 'Move a placement tree node,' and it disambiguates the item identifier from noteId. It does not explicitly distinguish this tool from the sibling move_placements, nor does it clarify the scope of the tree move.

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 guidance on when to use move_placement versus the sibling move_placements, or when not to use it. The only usage hint is the parenthetical 'placementId, not noteId,' which clarifies identity but not situational appropriateness.

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?

Adds substantive traits beyond the annotations: sequential execution, per-item results, partial success, no cross-request atomicity, and halting on authentication or permission errors. These are exactly the failure-mode and consistency facts an agent needs before issuing a bulk mutation, and nothing contradicts the annotation set.

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

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

Three short sentences, front-loaded with the operation and size bound, then the concurrency/atomicity contract. No filler, and every clause carries load-bearing 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?

Covers the batch-level contract well enough for a safe call, but with no output schema and zero parameter documentation, the description should at least sketch what a 'per-item result' contains and what the item fields mean. For a mutation accepting a nested structure, that gap is material.

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 the burden, but it only restates the batch ceiling of 50. The nested item fields — placementId, parentPlacementId, and especially position with its default of 0 — are left entirely unexplained in both places, and position semantics (ordering vs. root-level) are genuinely ambiguous.

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

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

States a specific verb and resource ('Move ... placements') plus the batch bound of 50, so the agent knows this is a bulk relocation operation. It never mentions the sibling move_placement (singular), so the agent must infer the single-vs-batch split on its own.

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?

'Move up to 50 placements sequentially' implies this is the batch path, but the description never names move_placement as the alternative for a single move, nor states any exclusion or prerequisite. Usage is inferable rather than explained.

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 flag destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely non-obvious behavior: this is an optimistic-concurrency write keyed on a version from a prior get_note call. It stops short of stating what happens on a version mismatch or that all prior body content is lost beyond the word 'complete'.

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 dense sentence with zero filler, and the destructive 'complete body' scope is front-loaded. The trailing 'as If-Match' leans on HTTP-header jargon that a calling agent may have to decode, a minor structural cost.

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

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

For a destructive, four-parameter mutation with no output schema, the description covers the one thing an agent cannot guess: content is fully overwritten and gated by a version token. Missing details are secondary but real, such as conflict/mismatch handling and whether metadata or tags survive the replacement.

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 25%, with just 'version' documented as a legacy alias for expectedVersion. The description compensates for the weakest spot by explaining that this version value must come from a prior get_note call, which gives expectedVersion real meaning. noteId and content remain undocumented in both places.

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

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

Specific verb 'Replace' plus a precise resource scope, 'the complete Markdown body', which implicitly separates it from the partial-mutation siblings (edit_content, append_content, replace_section). It does not name those siblings outright, so the differentiation is inferable rather than explicit.

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

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

'using the version from a prior get_note call as If-Match' establishes a real workflow prerequisite, implying get_note must precede this call. However, there is no explicit when/when-not guidance versus edit_content, append_content, or replace_section, which is the main decision an agent faces.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds real context beyond them: optimistic concurrency via required expectedVersion, atomic failure on ambiguous heading paths, and the exact-preservation guarantee for the heading and surrounding nodes. It does not explain what happens to nested subsections on failure in detail, or the role of idempotencyKey, but the safety-relevant behavior is well disclosed.

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

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

Five short sentences, front-loaded with the action and its preservation scope, then the prerequisite, parameter constraint, concurrency requirement, and failure mode. No sentence 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?

For a destructive mutation with no output schema and zero schema description coverage, the description supplies the essential operational context: precondition tool, concurrency token, preservation semantics, and atomic failure. The remaining gap is the undocumented text, noteId, and idempotencyKey parameters, which an agent must infer.

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 carries the burden and only partially does so: it defines oldText (exact Markdown body returned by get_section, including nested subsections), headingPath (hierarchy of heading titles), and expectedVersion (current version for conflict detection). It says nothing about text, noteId, or idempotencyKey, leaving half the parameters undocumented anywhere.

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

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

States a specific verb ('Replace') and a precisely scoped resource ('the body under a unique hierarchy of heading titles'), and clarifies the preservation boundary (heading and all outside Tiptap nodes). This implicitly separates it from whole-note tools like replace_content, but no sibling is explicitly named, so differentiation is inferred rather than stated.

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?

'Use get_section first' gives an explicit prerequisite and the correct workflow ordering. 'Ambiguous paths fail atomically' signals the failure mode. There is no explicit when-not guidance or named alternative for whole-note replacement, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds little beyond that, omitting search scope, archived-item handling, result limits, and what the candidate results contain.

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 search purpose and the placementId follow-up are both stated compactly.

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

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

For a tool with four parameters, no output schema, and zero schema descriptions, the definition is too thin. It does not explain how to scope searches, whether archived nodes are included, how many results are returned, or what a placementId is used for.

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 only implies that query is a title fragment and mentions placementId as an output value, but it says nothing about limit, includeArchived, or parentPlacementId.

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: find candidate placement nodes by a title fragment. It distinguishes the tool from a direct node lookup by emphasizing candidate search, though it does not explicitly contrast with siblings like get_tree_node or list_tree_children.

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 a workflow: first find candidates by title fragment, then navigate using their placementId values. However, it gives no explicit when-not conditions, alternatives, or prerequisites for choosing this tool over the many sibling tree-search and navigation tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully pins down exact-match (non-fuzzy) semantics and subtree scoping, but says nothing about archived-note handling, result volume/pagination, or case sensitivity of tag matching.

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 the resource and the exactness constraint front-loaded; no filler.

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

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

For a simple read-only lookup with annotations covering safety and no output schema, the description is close to sufficient. The remaining hole is includeArchived semantics and whether archived notes are silently excluded by default.

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

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

Schema coverage is 67% and the description restates the two documented parameters (exact tag, placement plus all descendants) without adding format or syntax detail. The third parameter, includeArchived, has no schema description and is never mentioned in the description, so its effect on results remains undocumented.

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

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

States a specific verb+resource ("Find notes with an exact Ygdria tag") and the optional scope. It never names or distinguishes itself from the obvious siblings search_notes and list_tags, so the agent has to infer the difference between exact-tag lookup and general note search.

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

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

Usage is only implied by "exact Ygdria tag" and the optional placement subtree; there is no explicit statement of when to prefer this over search_notes, nor any exclusion such as "use list_tags to discover tag names first." Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description does add real context not in structured fields — results carry noteId for follow-up note tools and snippets are plain text — but it says nothing about result limits, pagination, or ordering for a search operation.

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

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

Three short, front-loaded sentences with no padding; the returned-data note is placed last where it belongs. 'through ETAPI' is an implementation detail that adds little for an agent, keeping it just below top marks.

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

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

There is no output schema, and the description only partially compensates by explaining noteId and plain-text snippets. For a search tool it leaves out result caps, ordering, and whether empty results vs. errors are returned.

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 75%, close to the baseline threshold, and the schema documents query, tag, and placementId. The description only echoes the placement/descendant semantics already in the schema and says nothing about includeArchived, the one undocumented parameter.

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

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

States a specific verb+resource ('Search Ygdria notes through ETAPI') and adds scope via the optional placement-subtree restriction. It never distinguishes itself from the sibling search_by_tag or get_notes, which is the main gap for an agent picking among overlapping retrieval 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?

Usage is only implied: the placement sentence tells you an optional scoping mode exists but not when to prefer this tool over search_by_tag (which is presumably tag-only search) or list/get alternatives. No explicit when-not or prerequisite guidance.

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

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

Annotations already declare non-read-only, non-idempotent, and non-destructive, so the description's job is to add depth. It does exactly that by disclosing optimistic-concurrency semantics: on conflict it returns the latest note and the write does not apply, with an explicit anti-pattern (never retry stale version). It omits whether unset fields are preserved or cleared, which matters given destructiveHint=false.

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

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

Two tight sentences, front-loaded with the action and fields, followed by the failure-mode rule. No wasted wording and the most surprising behavior is stated directly rather than buried.

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

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

For a six-parameter mutation with no output schema and zero schema descriptions, the description covers the concurrency contract well but leaves gaps an agent would care about: whether passing a subset of fields replaces or merges the existing note, and what codeLanguage does. The versioning story is complete; the field-mutation story is not.

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 the load, and it partially does: 'current version from a read, resource, or prior write response' explains expectedVersion's semantics without naming it. It covers title/tags and calls the body 'content' (a naming mismatch), but says nothing about noteId or the unexplained codeLanguage parameter.

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 ('Update title, body, or tags') on a note, which is concrete enough to act on. It does not distinguish itself from overlapping siblings like update_tags, edit_content, or replace_content, which appear to touch the same fields, so an agent must guess which one applies.

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

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

Gives clear operational context: use a version obtained from a read, resource, or prior write response, and on conflict re-read and never retry the stale version. This covers when and how to invoke under contention, but there is no guidance on when to prefer this over the sibling tag/content tools.

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

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

Adds genuinely useful semantics beyond the annotations: unrelated tags are preserved, and additions win on overlap. Annotations already declare destructiveHint=false and idempotentHint=false, yet the description never explains how expectedVersion conflicts are reported or why idempotencyKey matters despite a non-idempotent hint.

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

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

Two short sentences, front-loaded with the merge guarantee and ending with the overlap tiebreak. No filler or repetition.

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

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

For a 5-parameter mutation tool with no descriptions, no output schema and no annotations explaining failure modes, the description should cover the concurrency and idempotency contract. It omits both, leaving an agent unable to call it safely under version conflicts.

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 5 parameters, so the description must carry semantics and does not. It covers the intent of addTags/removeTags only obliquely and says nothing about noteId, expectedVersion (optimistic concurrency) or idempotencyKey, which are the two parameters an agent is most likely to misuse.

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 pair and resource (add/remove tags) plus the key scoping property (merge, not replace). It does not name or distinguish itself from the near-neighbor siblings update_note or replace_content, and the phrase "the latest note" is slightly at odds with the required noteId parameter.

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

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

Usage is only implied: the caller infers this is the tool for incremental tag changes rather than full-note updates. There is no explicit 'use this instead of update_note' routing, and no precondition guidance around note identity or version state.

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