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

With no annotations the description carries the full burden, and it delivers two meaningful behaviors: missing parent documents are auto-created, and an existing path is not overwritten so duplicates are created instead. It stops short of stating permission/auth requirements or what the call returns, but the side-effect disclosure is genuinely useful.

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

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

Three tight sentences with zero filler; the core action is front-loaded and the path convention and collision behavior follow in order of importance.

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 write tool with no annotations and no output schema, the description covers action, path format, parent-creation side effect, and collision behavior — enough to call it correctly. Only permission/return-value context is absent, which is a minor 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%, so the schema already documents all three parameters including the `/Notes/Idea` example. The description largely repeats the path semantics rather than adding new syntax or constraints, and says nothing about `notebook` or `markdown`, so baseline 3 applies.

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

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

States a specific verb+resource ('Create a document from Markdown') and immediately qualifies the key input (Markdown source). It is clearly distinguishable from siblings like rename_document, move_document, or insert_block 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?

Usage is implied by 'Create a document' — this is the tool for making a new document. It notes the collision case (existing path is not overwritten, a new document is created alongside), which shapes when the agent should/shouldn't rely on it, but it never names alternatives such as get_document for checking existence or list_documents for browsing.

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

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

No annotations are provided, so the description carries the full disclosure burden. It usefully reveals the cascade behavior (children deleted, document-level deletion) that the name alone would not convey, but it never states that deletion is permanent/irreversible, whether any auth or permission is required, or whether the operation can be undone.

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, zero filler, with the destructive cascade warning front-loaded before the advisory prerequisite. Every sentence carries distinct, actionable 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 one-parameter destructive tool with no annotations and no output schema, the description covers the critical behavioral surprise (cascade deletion) and the recommended pre-check. The main remaining gap is the absence of any statement about permanence or recovery.

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 already documents it at 100% coverage ('Block ID to delete'). The description's 'by ID' adds no format or source-of-ID information beyond what the schema 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 ('Delete a block') and adds the non-obvious scope 'and its children', which an agent needs to know before calling. The additional note that deleting a document block removes the whole document further sharpens what the tool actually operates on.

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 recommends confirming the target via `get_document` or `search_notes` first, naming concrete siblings. It does not, however, say when not to use this tool (e.g. use `remove_document` instead for full-document removal) or distinguish it clearly from the parallel `remove_document` sibling.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose what each format returns. However, it says nothing about behavior on an invalid/missing ID, permission requirements, or whether the read has side effects (it does not explicitly state this is a read-only, safe operation).

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

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

Two tightly packed sentences with zero filler; the core action and the format distinction are front-loaded, and 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?

With no output schema and no annotations, the description adequately covers both parameters and the differing return shapes for each format. It is slightly short of complete because error handling and the read-only nature of the operation are left unstated.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining why to pick kramdown (it surfaces block attribute IDs for locating nested blocks to edit), a use case the schema does not convey.

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 one block by ID'), making it easy to pair with insert_block/update_block/delete_block siblings. It does not explicitly name an alternative such as get_document or a traversal tool, 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?

Usage is only implied: the reader infers this is for fetching a single known block ID. There is no guidance on how to obtain a block ID, no when-not-to-use (e.g. listing many blocks), and no pointer to the block-editing tools, other than the indirect hint about 'locating nested blocks to 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?

With no annotations, the description carries the full burden, and it does disclose the return format (Markdown) and accepted identifier forms. It does not describe failure behavior for an unknown ID/path, permission requirements, or whether content is truncated for large documents.

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

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

Three short sentences, front-loaded with the core action and return type, then the argument format, then the role. No filler or redundant clauses.

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

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

For a single-parameter read tool with no output schema, the description covers what it returns (Markdown) and how to identify the document, which is most of what an agent needs. Error/edge-case behavior on invalid identifiers is the only notable omission.

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

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

Schema coverage is 100% and the single 'doc' parameter already documents both the ID and the `/Notes/My doc` path form, so the description largely restates it. Baseline 3 is appropriate when the schema does the heavy lifting; the description adds no extra format or escaping detail.

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

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

The description gives a specific verb and resource ('Read a document as Markdown') and states the return format and identity that content reading is its role ('primary way to read note content'). It implies a contrast with get_block but never names an alternative sibling, so it stops short of full sibling differentiation.

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?

Saying it is 'the primary way to read note content' implies when to reach for it, but there is no explicit when-not guidance and no mention of get_block, search_notes, or list_documents as alternatives. Usage is inferable but not spelled out.

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

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

With no annotations, the description carries the full behavioral burden: it discloses the two insertion modes and the exactly-one constraint, which is useful. However it says nothing about write permissions, behavior on invalid/missing IDs, or the response, leaving meaningful behavioral gaps for a mutation tool.

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

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

Two tight sentences; the core action is front-loaded and each clause (parent_id, previous_id, exclusivity) earns its place with no filler.

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

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

For a simple 3-param tool with no annotations and no output schema, the description covers the essential operation and placement semantics. Only secondary details (permissions, error/response behavior) are absent, which is a minor 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 coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining the semantic relationship between parent_id and previous_id and the 'exactly one' exclusivity rule, which the per-field schema descriptions do not express.

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 (append Markdown as new blocks) and disambiguates the two placement modes. It clearly differs from update_block/delete_block/get_block by operation type, but names no sibling explicitly, so it falls just short of 5.

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

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

Gives concrete invocation guidance: parent_id appends inside a block (document ID for documents), previous_id inserts after a block, and 'provide exactly one of them' states the mutual-exclusion rule. It covers how to use the tool but offers no comparison to alternative insertion/edit 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?

No annotations exist, so the description carries the full behavioral burden. It does disclose the deterministic sort order ('most recently updated first'), which is a genuinely useful trait, but says nothing about pagination, result caps, or truncation behavior for a listing 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 tight sentences with the primary purpose front-loaded and no filler. Every clause (scope, ordering, use case) earns its place.

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

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

For a simple zero-required-param list tool with 100% schema coverage and no output schema, the description covers scope, ordering, and intent adequately. Only minor gaps remain, such as pagination or how results are shaped when listing across all notebooks.

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% with only 2 params, so the baseline is 3. The description reinforces the notebook-scoping concept ('in one notebook' / 'workspace') but adds no syntax or format detail beyond what the schema's parameter descriptions already provide, including the default limit.

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 documents') plus scope ('in the workspace or in one notebook') and ordering ('most recently updated first'). This clearly separates it from mutation siblings like create_document/rename_document, though it doesn't explicitly contrast with the read sibling search_notes beyond the word 'searching'.

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

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

The phrase 'Useful for browsing what exists before searching' implies when to use it relative to searching, but it never names search_notes as the alternative nor states exclusions. Usage is suggested rather than prescribed.

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

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

No annotations are provided, so the description carries the full burden, and it does meaningful work: it discloses that the result is exhaustive ('every notebook') and names the returned fields, which matters because there is no output schema. It does not mention pagination or sorting behavior, which is the remaining gap.

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

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

Two sentences, zero filler. The scope and returned fields are front-loaded and the usage instruction follows immediately; every clause earns its place.

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

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

For a zero-parameter, read-only listing with no output schema, the description correctly compensates by naming the returned fields and stating the workspace-wide scope. Only the absence of any note on result size or ordering keeps it from being fully 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to clarify beyond confirming that the listing is unfiltered and workspace-wide.

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 ('List every notebook') and even enumerates the returned fields (ID, name, open state), with a parenthetical gloss of the domain term (思源笔记本). It does not explicitly distinguish itself from the similarly named sibling list_documents, so it stops short of a 5.

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

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

The second sentence gives explicit when-to-use guidance and an ordering hint: 'Call this first when you need a notebook ID for other tools.' No alternatives exist among siblings for this resource and no exclusions are stated, so it is clear context without full when/when-not coverage.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose non-obvious destination semantics (a notebook target places the document at that notebook's root), which goes beyond a bare 'move'. But it is silent on permissions, whether descendants move with the document, collision/overwrite behavior, and reversibility of a mutation.

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, zero filler, and the core purpose is front-loaded before the parameter clarification. Every clause earns its place.

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

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

For a two-parameter tool with full schema coverage and no output schema, the description covers purpose and destination semantics adequately. Against zero annotations, though, it leaves the safety and side-effect profile entirely unstated, which is thin for a mutating operation.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description restates the `to` parameter's dual meaning and adds the 'notebook's root' detail, which is a marginal value-add over the schema text rather than new syntax or format guidance.

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 plus resource ('Move a document') and immediately disambiguates the two modes of the operation: reparenting under another document vs. relocating into a notebook. This is clearly separable from siblings like rename_document, remove_document, and create_document, which do different things to a 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?

Usage is implied by the action ('move a document' when you want it elsewhere), and the description usefully clarifies what each destination type means. However, it names no alternatives, no preconditions (e.g. needing write access to both source and destination), and no cases where the move would fail or should be avoided.

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

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

With no annotations, the description carries the full burden, and it does disclose the important trait that deletion is soft: the document goes to the workspace trash (数据历史) and is recoverable. It omits permission requirements, idempotency, and what happens when the ID/path is invalid.

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

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

Two short sentences, front-loaded with the action, and the recoverability detail is placed where it is most useful. The 'Accepts a document ID or a path' clause is redundant with the schema and could be cut.

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 one-parameter mutation tool with no output schema, the description covers the essential behavioral fact (soft delete with recovery), which is what an agent most needs to act safely. Remaining gaps are permission and failure-mode details that are secondary 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?

Schema coverage is 100% with the single 'doc' parameter already documented as 'Document ID or path', and the description repeats exactly that. Baseline 3 applies since the schema does the heavy lifting and the description adds no format or syntax detail.

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

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

States a specific verb and resource ('Delete a document') and clarifies accepted identifier forms. It does not explicitly contrast with the nearby delete_block or move_document siblings, so an agent must infer that this targets whole documents rather than blocks.

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 or mention of alternatives such as move_document for relocation versus deletion. The recoverability note implies the operation is safe-ish, but the description never says when an agent should choose this over other mutation tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It mentions the operation is a rename but says nothing about permissions required, reversibility, whether renaming preserves the document identity, or failure behavior for a mutation tool.

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

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

Two short sentences with the purpose front-loaded and no filler. Efficient, though the second sentence duplicates schema information rather than earning its place.

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

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

A simple two-parameter mutation with fully documented params and no output schema, so little is strictly needed. It is adequate, but the absence of any behavioral or usage context leaves real gaps for an agent deciding how and when to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents both 'doc' and 'title'. The description's note that 'doc' accepts an ID or a path marginally reinforces the schema but adds no new syntax or constraint detail. Baseline 3.

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 ('Change the title of a document'), which is immediately clear. However, it offers no differentiation from siblings like move_document or update_block, which an agent might confuse with renaming.

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 alternatives, prerequisites, or exclusions. The description only restates the operation, leaving usage entirely to inference.

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

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

With no annotations, the description carries the disclosure burden, and it does state what comes back (matching blocks, IDs, document paths) — useful because there is no output schema. It never states the read-only nature or result paging behavior, but for a search tool the safety profile is clear from the wording.

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: purpose and return shape first, usage context second, syntax third. No filler and the most important information is front-loaded.

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 what the tool does, when to reach for it, what it returns, and how to form queries — enough to call it correctly given no annotations and no output schema. Only minor gaps (result ordering, paging guidance) remain, and paging is already partly covered by the schema.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine value beyond the schema by documenting SiYuan query syntax (AND, quoted phrases, OR, negation, wildcard) that an agent could not infer from 'Search keywords.'

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 ('Full-text search across the workspace') and goes further by describing the result shape ('matching blocks with their IDs and document paths'). This distinguishes it clearly from retrieval siblings like get_document, get_block, and sql_query.

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 to locate content before reading or editing it' gives a clear when-to-use context that positions it ahead of the read/edit siblings. It stops short of naming an explicit alternative (e.g. sql_query for structured queries) or stating when-not to use it, so it falls just short of the top score.

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

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

With no annotations, the description carries the full burden and does well: it discloses read-only semantics, the permitted statement classes (SELECT/WITH/EXPLAIN), and the kernel's 64-row result cap. It omits permission/auth requirements and what happens if a forbidden statement is submitted, 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?

Front-loads purpose and routing, then packs table schema and hard limits into two tight sentences with no filler. Every clause carries actionable 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 raw SQL tool with no output schema, the description covers the query surface and row cap well, but does not describe the shape of returned results (columns/rows) beyond the cap, leaving the agent to infer the output format.

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% (baseline 3), and the description adds meaningful constraints beyond the schema's 'single read-only SQL statement': the allowed statement types and the primary `blocks` table with its column list. That extra context helps the agent construct a valid `stmt`.

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

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

States a specific verb and resource ('Run a read-only SQL query against the SiYuan index') and explicitly positions it against siblings by scoping it to 'questions the other tools cannot' with concrete examples (counting blocks, filtering by tag/attribute). An agent can distinguish it from search_notes/get_block 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 a clear selection condition — use this when the other tools cannot answer, with examples of such cases. It does not name a specific sibling as the preferred alternative or state explicit exclusions (e.g. 'do not use for full-text search'), so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the block type can change and that lock_type guards against that, which is real mutation semantics. It stops short of stating permissions required, reversibility, or what a failed update returns.

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, then the type-change caveat, then the ID-sourcing prerequisite. 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 an unannotated mutation tool with no output schema, the description covers purpose, the type-change behavior, the lock_type safety path, and where to get the ID. Missing only side details like permission requirements and error semantics, which is a minor 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 coverage is 100%, so the schema already documents all three parameters, including lock_type's refusal behavior. The description reframes lock_type behaviorally ('unless lock_type is true') but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Replace the content of an existing block with new Markdown'), making the mutation contract immediately clear. It is cleanly distinguishable from insert_block, delete_block, and get_block, which appear as siblings.

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

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

Explicitly gives the prerequisite for obtaining the required id ('Get the ID from get_block or search_notes first'), naming the alternative tools. It does not, however, state when to choose this over insert_block or when an update is inappropriate.

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