Nodiom Cloud

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds the default-column behavior and the permanence of the card id, but says nothing about what a non-idempotent retry does (duplicate cards) or any permission requirements.

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 core action and side effect before the usage hint. Each sentence carries information, though 'with a permanent id' and 'Returns the card's id' partially overlap.

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 full schema coverage, rich annotations, and an output schema covering the return value, the description supplies everything else an agent needs: default placement, the creation side effect, and the intended hand-off use case.

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

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

Schema description coverage is 100%, so all six parameters (including title, brief, criteria, agent) are already documented in the schema. The description's only parameter-level contribution, the default column behavior, essentially restates the schema's own column description, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Adds a card to a board') and states the side effect (permanent id) plus the return value. This cleanly separates it from siblings like board_create (makes the board), board_update_card, and board_move_card.

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 concrete usage context ('hand work to another agent or to a person') and clarifies default placement behavior. It does not name alternative tools or when-not-to-use this one, so it stops short of full routing guidance.

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

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

Annotations already declare the write/idempotency/destructive profile, so the bar is lower. The description adds real behavioral context beyond them: the return value (doc_id), the default column set when columns is omitted, and the ordering semantics of the last column and review_column.

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

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

Four sentences, no filler, and the definition of the artifact is front-loaded before the defaults and column semantics. Slightly dense but every sentence 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?

An output schema exists, so return-value detail is not required, yet the doc_id mention ties the artifact to it. Combined with defaults, handoff conventions, and review-column semantics, the description is complete for a 3-parameter creation tool with full schema coverage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning the schema does not: the concrete default column names, the agent-handoff convention, and the semantic role of the last column versus review_column, which clarifies intent beyond the schema's structural rules.

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 ('Creates a board') and then defines what a board actually is ('a shared Markdown document whose columns are ## headings and whose cards are checklist items'), which lets an agent distinguish it conceptually from nodiom_create_doc among the siblings. It also states the returned handle (doc_id).

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 concrete usage context: default columns, and a named alternative column set ('Received, Doing, Done') for work handed between agents. It does not explicitly state when NOT to use this tool or name which sibling handles a similar need, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real value: permanence ("for good") and the non-obvious review-step restriction that would otherwise cause a failed call. It stops short of noting what else is destroyed (replies, attachments) or required permissions.

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 action front-loaded and the constraint following. Nothing repeats the title or annotations wastefully.

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 and annotations carry return values and safety semantics, so the description only needs the operational gotchas — and it supplies the most important one. It leaves minor questions open (whether attached replies vanish with the card, auth requirements), keeping it just under complete.

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

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

Schema description coverage is 100%, and each parameter already documents its source (board_create/nodiom_list_docs, board_read, API key default). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Removes a card from the board") with a permanence qualifier that distinguishes it from the reversible board_move_card or board_update_card. An agent can tell what this does without opening the schema.

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

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

Explicitly names the blocking precondition (a card awaiting review on a board with a review step cannot be deleted) and routes to the alternative remedy ("move it instead"). Both when-not and alternative are stated outright.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), while the description adds atomicity guarantees ('never exists twice or not at all, even while other agents are writing'), the review-gate permission model, refusal of review-skipping moves, and the reviewer-note-on-return behavior. That is substantial behavioral context beyond the structured fields.

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

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

Front-loads the atomicity guarantee and routing triggers before the review-workflow detail, and every sentence carries workflow or constraint information. The pickup/work/finish cadence is slightly repetitive but not wasted for a multi-state tool.

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

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

A stateful mutation tool with a review gate is fully covered: entry conditions, refusal cases, the alternative for criteria updates, and what comes back when picking up a sent-back card. An output schema exists, so return values need no further explanation.

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

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

Schema coverage is 100%, so all five parameters, including `to`, `note`, and `agent`, are already fully documented in the schema. The description reinforces the reviewer-only use of `note` but adds no format or syntax detail beyond it, so the baseline of 3 is correct.

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 with scope: 'Moves a card to another column in one atomic step.' This distinguishes it cleanly from siblings like board_update_card (which ticks criteria) and board_add_card, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use triggers ('when you pick it up, as you work it, and when it's finished'), names the alternative for criteria ('board_update_card'), and states the stop condition at a review column plus which moves are refused. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false). The description adds genuinely new behavioral facts: cards are addressed by id and never by position, and review_notes are returned oldest first with the last note carrying the required change when a card comes back. It does not mention behavior on a missing or malformed doc_id.

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

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

Three sentences, front-loaded with the return shape, then the usage condition, then the review_notes detail. Every sentence carries information, though the review_notes sentence is somewhat dense and could be tightened.

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

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

With an output schema present, return values need not be re-explained, and the annotations carry the safety profile; the description fills in the remaining gaps an agent needs (when to read, how cards are identified in subsequent calls, how review feedback surfaces). Only error/empty-board behavior is unaddressed.

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

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

Schema description coverage is 100% for the single doc_id parameter, and the schema already says where the id comes from ('as returned by board_create or nodiom_list_docs'). The description adds nothing about the parameter itself; the 'addressed by id' statement concerns cards inside the document, not the input. Baseline 3 with the schema doing the work.

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 ('Returns a board's columns and cards as JSON') and enumerates what comes back (card id, owner, acceptance criteria). The routing advice about reading before picking up, adding or moving work also separates it in practice from sibling writers like board_add_card and board_move_card.

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 the board before you pick up, add or move work' gives a concrete trigger tied to the sibling write tools, so an agent knows when to reach for this rather than one of them. It stops short of naming alternatives explicitly (e.g., board_wait for blocking, board_reply for responding), so no true when-not-to-use 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 a non-destructive, non-idempotent write, and the description adds real context: the reply is nested under the reviewer's latest note, attributed to the caller, and has no side effects on card state. It stops short of noting visibility/permissions or rate behavior, so it is strong but not exhaustive.

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?

Purpose is front-loaded, and the inline example ('Agreed, cutting it to four lines') clarifies tone and intent efficiently. Three sentences is appropriate; the parenthetical example is the only slight embellishment but it earns its place by disambiguating the reply's nature.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile; the description supplies the workflow placement and the non-effects. Complete enough for correct invocation, with only minor gaps around who can see the reply.

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

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

Schema description coverage is 100%, so all four parameters (text, agent, doc_id, card_id) are already documented with formats and defaults. The description only implies the meaning of 'text' via the example reply; it adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Answers the person who reviewed a card') and explicitly delineates scope against siblings: it does not move the card, change its content, or serve as a review decision. An agent can distinguish it from board_update_card or board_move_card without opening a schema.

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

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

Gives an explicit trigger ('after a card is sent back with a note, before you redo the work') and an explicit exclusion ('can never stand in for a review decision'). The when-to-use and when-not-to-use are both stated, not inferred.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true): it discloses what is preserved (id, column, owner, review notes), what the destructive behavior actually means (criteria replace the entire list, so omitted criteria are dropped), and a state precondition tied to the review workflow. That is exactly the kind of context structured hints cannot convey.

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

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

Three sentences, all load-bearing: what it does, how to send partial updates and the list-replacement rule, then the review-state exclusion. Front-loaded with the core action and free of 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 partial-update mutation with 6 params and an output schema (so return values need no explanation), the description covers scope, preservation semantics, list-replacement behavior, and the blocking precondition. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by clarifying the non-obvious replacement semantics of the criteria array ('send every criterion you want kept, ticking the ones that are met') — a behavior the schema cannot express despite its detailed field descriptions.

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 ('changes') plus resource ('a card') and enumerates exactly which fields are editable (title, brief, acceptance criteria). The phrase 'in place' and the field list separate it from board_move_card, board_add_card, and board_delete_card without needing to open any schema.

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

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

Gives an explicit when-not condition ('on a board with a review step, cards waiting for review or already approved can't be edited') and partial-update guidance ('give only the parts to change'). It never names a sibling alternative for a given intent, so it stops 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 readOnly, idempotent, non-destructive, so safety is covered; the description adds real behavioral detail the annotations don't: it blocks up to timeout_seconds, returns on first decision after since, marks sent-back cards as picked up, and enables cursor continuation. It doesn't discuss rate limits or error conditions, keeping it just below top marks.

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

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

Front-loaded with what it does, followed by return conditions, guidance, and parameter semantics; four sentences each carry useful information, though the pickup note could be trimmed 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?

With an output schema present, the description needn't explain returns; it covers blocking behavior, timing, continuation, and the pickup side-effect. Minor gaps like failure modes or concurrency are not essential for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond the schema by clarifying how 'since'/next_since drives continuation and that timeout_seconds 0 means a non-blocking check, plus the side-effect on sent-back cards that affects interpretation of results.

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 (waits) and resource (review decisions on a board), and distinguishes itself from the obvious alternative by naming board_read and explaining it replaces polling.

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

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

Explicitly says to call it after moving work to review and instead of polling board_read, explains timeout_seconds 0 as a non-blocking check, and describes continuation via next_since. Alternatives and timing conditions are fully specified.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact, 'Changes are saved automatically,' i.e. implicit persistence, but says nothing about failure modes, permission requirements, or how concurrent appends are handled.

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 operation and insertion point front-loaded, and the persistence note second. Nothing is padded, though the second sentence is close to filler given how little it specifies.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety profile. What is missing is routing relative to nodiom_write and any note on non-idempotency consequences, which matters for an append operation an agent may retry.

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 selector description already explains the index-vs-contains identity problem in detail. The description contributes no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb (appends) and resource (content in a section) plus the insertion point ('after the last item'), which is more precise than a generic write. It does not, however, contrast itself with the nearby nodiom_write sibling, so an agent must infer which one 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?

No when-to-use guidance and no alternatives named, despite nodiom_write being an obvious candidate for the same document. The reader is left to guess whether append vs write is a matter of intent, selector form, or position.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false; the description adds genuinely new behavior by stating the no-op on duplicate document IDs, which is exactly the kind of side-effect disclosure annotations cannot express. Minor tension: a same-argument no-op is effectively idempotent, while idempotentHint is false, but this reads as an edge-case clarification rather than a claim of a different operation class.

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

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

Two short sentences with zero filler; the primary action is stated first and the duplicate-handling caveat immediately follows. Nothing is repeated from the title or annotations.

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 annotations covering safety and mutability, an output schema covering return values, and full schema coverage on the two parameters, the definition supplies what's uniquely missing: the exists-and-no-op semantics. It stops short of saying what is returned or whether existing content is ever overwritten, which for a create-only tool would be the final detail.

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

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

Schema description coverage is 100% and both required parameters are documented there, including examples for doc_id and the Markdown semantics of content. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Creates a new document in Nodiom Cloud storage'), which is clearly distinguishable from readers like nodiom_get_doc or nodiom_list_docs. However, it never contrasts with the sibling nodiom_write, so an agent cannot tell from the description alone whether nodiom_write would also create a missing document.

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?

'Does nothing if the document already exists' implicitly tells the agent to use another tool (nodiom_write / nodiom_append) for existing documents, which is useful routing context. But that alternative is never named and there are no explicit exclusions or prerequisites, leaving the guidance inferential rather than 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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one genuinely new behavior ("changes are saved automatically"), but omits what else is destroyed — e.g. whether deleting a section also removes its child nodes — which matters most for a destructive 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?

Two short, front-loaded sentences with zero filler: the action first, the auto-save side effect second. Nothing could be cut without losing information.

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

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

An output schema exists, so return values need not be explained, and annotations carry the destructive/idempotent story. However, for a subtree-deleting mutation the description should say what happens to children of a deleted section and whether a non-matching selector no-ops or errors; those gaps keep it at minimum-viable rather than complete.

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

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

Schema description coverage is 100%: doc_id and selector are documented at length, including selector syntax and the singleton-match error rule. The description's phrase "node or section matched by the selector" adds only a marginal gloss over what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ("Removes the node or section") and scopes it via the selector, which separates it from nodiom_write/nodiom_append in sibling terms. It stops short of naming the alternative tools explicitly, so it is clear but not fully differentiated.

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 mention of alternatives such as nodiom_write (which likely overwrites) or nodiom_tree. Usage is only implied by "matched by the selector"; an agent is left to infer when deletion is preferable to rewriting.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is covered structurally. The word 'Permanently' adds a mild nuance about irreversibility, but it largely restates what destructiveHint already conveys, and nothing is said about permissions, cascading effects, or error behavior when the doc_id is missing.

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

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

A single front-loaded sentence with the destructive verb and resource at the front and zero redundant wording. 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?

An output schema exists, so return values need not be described, and the single parameter is fully documented in the schema. However, the description never addresses how this tool relates to the sibling nodiom_delete, leaving a real risk of wrong-tool selection for a destructive operation.

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

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

Only one parameter (doc_id) and schema description coverage is 100%, with examples embedded in the schema, so the baseline is 3. The description adds no format or constraint details beyond what the schema already 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?

States a specific verb and resource ('Permanently deletes a document') and names the storage system. It is clear on its own, but it does not differentiate itself from the sibling nodiom_delete, so an agent cannot tell from the description alone which delete tool applies to documents.

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

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

No when-to-use guidance, no prerequisites, and no mention of the alternative nodiom_delete or nodiom_get_doc. The agent must infer applicability 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only that the return format is Markdown and the scope is the whole document, which is modest but genuine added context beyond the annotations.

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

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

A single front-loaded sentence with no redundant or filler clauses — the return format is stated immediately. It is efficient, though the extreme brevity is under-specification rather than disciplined conciseness in the usage dimension.

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 is simple (one required param) and an output schema exists, so return values need not be explained. However, with several overlapping read-oriented siblings (nodiom_read, nodiom_query, nodiom_list_docs), the definition leaves the agent without enough context to confidently pick this tool.

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

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

Only one parameter exists and its schema description coverage is 100%, including concrete ID examples, so the schema carries the full burden. The description adds no format, constraint, or lookup guidance beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Returns the full Markdown content of a document'), and the qualifier 'full' signals scope. It does not distinguish itself from close siblings such as nodiom_read or nodiom_query, leaving the agent to 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 when-to-use guidance, no conditions, and no mention of the obvious alternatives (nodiom_read, nodiom_list_docs, nodiom_query). The agent gets no routing help for choosing this over its siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds the useful fact that only IDs are returned, but says nothing about pagination, result limits, or ordering for a potentially large listing.

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. Nothing in it is redundant and it fits the trivial shape of the tool.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile for this zero-param read. The only residual gap is scale behavior (pagination/limits) on a listing that could be large.

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 per the baseline this dimension starts at 4; there is no parameter meaning for the description to compensate for, and schema coverage is 100%.

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 ('Returns') and resource ('all document IDs available in Nodiom Cloud storage'), and usefully narrows the return to IDs rather than document content, which separates it in spirit from nodiom_get_doc/nodiom_read. It never names a sibling, so differentiation is inferential 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?

No when-to-use guidance and no mention of alternatives such as nodiom_read_list, nodiom_tree, or nodiom_get_doc. The agent is left to guess whether this or a sibling is the right entry point for discovering documents.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only a list of returned fields, which overlaps with the output schema; it discloses nothing about selector resolution behavior, error conditions, or latency.

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 zero filler, and the field list is the highest-value content placed first. Nothing to trim.

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?

Return values are covered by the output schema and safety by annotations, so the description needn't repeat them. But with eight nodiom siblings sharing the same document namespace, the missing routing guidance (read vs tree vs query) leaves a real gap an agent must resolve by guessing.

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

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

Schema description coverage is 100%, so both params (doc_id, selector) are already richly documented, including selector syntax, the contains-vs-index guidance, and the exact-one-match error rule. The description adds no parameter meaning beyond 'a location', so the baseline of 3 is appropriate.

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

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

States a specific verb (returns) and resource (structural metadata about a location) and enumerates the returned fields (exists, type, depth, childCount), which is more concrete than the title 'Check a section'. It does not, however, distinguish itself from siblings such as nodiom_read or nodiom_tree, 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?

There is no statement of when to use this tool versus nodiom_read, nodiom_tree, or nodiom_read_list, all of which operate on the same documents. The closest thing to guidance is the implicit 'check before write' framing in the annotations title, which the description never makes explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is fully covered. The description adds no behavioral context beyond restating its own title — no error semantics (e.g., non-matching or ambiguous selectors), no note that it is a pure read against a versioned store, nothing the annotations and schema don't already convey.

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

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

A single front-loaded sentence with the verb first and zero filler or redundancy. Nothing in it is wasted, even if more substance would have been welcome.

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 is structurally simple (2 required params), annotations are complete, the schema documents both parameters well, and an output schema exists so return values need no prose. What is missing is routing context: with four sibling read tools (get_doc, read_list, query, tree) an agent gets no help picking this one, which is the remaining gap.

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 selector field is unusually rich, including worked examples and the contains-vs-index rationale with a concrete race-condition warning. The description contributes nothing beyond the phrase "structural location," so this sits at the baseline 3 that fully-documented schemas earn.

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 ("Returns the Markdown content") and scopes it to "a structural location within a document," which is clearer than the bare title "Read section." However, it never distinguishes this from close siblings like nodiom_get_doc, nodiom_read_list, nodiom_query, or nodiom_tree, 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 when-to-use, when-not-to-use, or alternative named. The phrase "structural location" implies the tool is for targeted, selector-based reads, but the description never says when to reach for this versus nodiom_get_doc (whole document) or nodiom_read_list (listing). Any practical guidance lives only in the selector schema field.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the return shape (JSON array of strings), which is mild added value, but says nothing about error behavior or selector-matching failure modes. A 3 is appropriate with annotations carrying 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?

A single front-loaded sentence with no filler. It is efficient, though the brevity leaves nothing to route usage or caveats.

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 only 2 parameters, a full output schema, and complete annotations, the definition is technically callable as written. The missing piece is routing guidance against the many read-shaped siblings, which this description never addresses.

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

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

Schema coverage is 100% and the selector description in the schema is unusually rich (contains-form guidance, exact-match requirement). The description's "under a selector" adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Returns all list items under a selector") plus the return shape, so the agent knows what it does. It does not, however, differentiate itself from siblings like nodiom_read or nodiom_query, which also read content.

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 indication of when to prefer this over nodiom_read, nodiom_query, or nodiom_tree, and no prerequisites or conditions given. The agent must infer usage 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the return shape ('nested JSON tree'), without noting depth, size limits, or behavior on invalid doc_ids.

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 what the tool returns, followed by the single usage cue. No filler.

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

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

An output schema exists, so return-value explanation is unnecessary, and the annotations cover the safety profile for a trivial one-parameter read. The only real gap is the lack of differentiation from sibling read/get-doc 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?

Only one parameter, and the schema documents it at 100% coverage with format hints and examples. The description adds nothing about doc_id semantics, so the baseline 3 applies.

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

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

States a specific verb ('Returns') and resource ('full structural outline of a document') plus the output shape ('nested JSON tree'), which distinguishes it from plain read tools like nodiom_read or nodiom_get_doc. It stops short of naming those siblings explicitly, so an agent must infer the distinction rather than be told.

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 this first to understand a document's structure' gives a sequencing hint, but there is no explicit when-not guidance and no named alternatives (e.g., use nodiom_get_doc for raw content, nodiom_read for text). Usage is implied rather than defined.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds real value beyond them: that the heading survives the replacement (i.e. only the body is destroyed) and that changes persist without an explicit save call. It does not mention auth requirements or the race-condition risk that the selector schema warns about.

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

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

Three short sentences, front-loaded with the operation, then the preservation guarantee, then the persistence behavior. Every sentence carries information an agent needs and none is padding.

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

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

With an output schema present, return values need no explanation, and the annotations carry the safety contract. The description covers what gets replaced and what is preserved, which is the key gap for a destructive write. It is only slightly thin on when this tool should be chosen over nodiom_append.

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

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

Schema description coverage is 100% and the schema itself is unusually rich, including the li[0] vs contains= identity warning. The description adds nothing about doc_id, selector, or the content/new_content alias, so this sits at the baseline where the schema does all the work.

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?

"Replaces the content at a selector" gives a specific verb (replaces) and resource (section content at a selector), which implicitly contrasts with the append sibling. It stops short of naming nodiom_append or any sibling explicitly, so an agent must infer the boundary from the verb 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 never states when to use this over nodiom_append, nodiom_create_doc, or other write paths, nor any prerequisites. An agent reading only this text gets no routing guidance between the two mutation siblings.

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