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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds real value with the title-uniqueness rejection rule and the supported type list, but says nothing about where the new column is placed, whether options are ignored for non-select types, or that expectedRevision guards against stale writes — that last point lives only in the schema.

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

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

Three short sentences, front-loaded with purpose, then capability, then the single failure condition. No filler and nothing repeated from the schema beyond a brief type roll-up.

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

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

With a full-coverage schema, an output schema present, and annotations covering the safety profile, the description covers what is needed to call the tool. Minor gaps remain: no mention of column placement/ordering or whether `options` applies only to select types.

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%, including the enum for `type` and a detailed note on `expectedRevision`, so the schema does the heavy lifting. The description's type enumeration merely restates the enum; its only added semantic is the interaction between type='title' and an existing title column.

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?

Opens with a specific verb+resource pair ('Add a column to an existing AFFiNE database block'), which clearly separates it from row-oriented siblings like add_database_row or read_database_columns. It stops short of naming a sibling or explaining when reading columns first is advisable, so it is clear but not differentiating.

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 mutation verb and the 'existing database block" precondition, and one constraint (title rejection) is stated. There is no explicit guidance on prerequisites (reading columns first, obtaining databaseBlockId) or on choosing this tool versus compose_database_from_intent for bulk setup.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive and open-world. The description adds real context beyond them: title column text is stored on the row paragraph block as a side effect, and select columns auto-create missing options by label. It does not mention the stale-revision rejection path even though expectedRevision exists, so it is not a 5.

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

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

Four short sentences with no filler, and the core action leads. Each sentence carries a distinct fact: purpose, cell mapping, title storage location, select option behavior. Nothing is repeated and nothing is buried.

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

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

An output schema is present, so return values need no explanation. The description covers purpose, cell shape, and the two non-obvious write side effects (title paragraph block, auto-created select options) for a 6-parameter mutation tool with a nested object. Nothing an agent needs in order to call it correctly is missing.

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's cells description already covers delta arrays, LinkedPage references and select labels in more detail than the description's one-line summary. The description's 'mapped by column name or column ID' adds no meaning 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?

The description opens with a specific verb and resource: 'Add a row to an AFFiNE database block.' That is unambiguous and distinguishes it from update_database_row and delete_database_row by verb alone. It does not name those siblings explicitly, which keeps it just short of a 5.

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

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

Usage is only implied: the description instructs how to supply cell values, which suggests this is the tool for populating a database block. It never states when to use add_database_row versus update_database_row, nor any prerequisites such as whether the database block must already exist. Adequate but with a clear gap.

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 write (readOnlyHint=false), non-idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds the useful 'allow-list' framing that clarifies this is explicit membership granting, but it does not address the non-idempotent hint — what happens on re-adding an existing member — 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?

Two sentences, zero filler, with the core action first and the disambiguation second. 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?

An output schema exists so return values need no explanation, and annotations cover safety. For a mutation with openWorldHint and non-idempotent semantics, a note on duplicate-membership behavior would close 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% with only 3 parameters, so collectionId, docId, and workspaceId are already fully documented in the schema. The description mentions the doc id and collection concept but adds no format, ordering, or fallback detail beyond the schema.

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

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

States a specific verb and resource ('Add an existing document id to an AFFiNE collection allow-list') and names the sibling that covers the other membership model. An agent can distinguish this from update_collection_rules without opening either 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 routes the agent: use update_collection_rules instead when membership should be rule-driven. That is a clear when-to-use-alternative signal, but it gives no prerequisites for this tool itself (e.g. doc must exist, collection must exist, what happens if the doc is already a member).

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 readOnly/destructive/idempotent profile. The description adds concrete limits (500 nodes, depth 64), the shape-only restriction, and that hierarchy and layout persist together, though auth/permission behavior is absent.

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 tight sentences; operation and ordering are front-loaded before limits and return details. 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?

The output schema covers return values, annotations cover safety, and the description adds limits and layout persistence. It is nearly complete, though it could clarify the role of docId/workspaceId for an agent unfamiliar with the hierarchy.

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

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

With only 14% schema description coverage, the description usefully defines beforeId insertion semantics and the parentId/mindmapId relationship. However, required docId and text plus optional workspaceId remain unexplained, so it only partially compensates.

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?

Opens with a specific verb and resource ('Add one native child shape') and names the exact parent/mindmap scoping. This clearly distinguishes it from update_mindmap_node and reparent_mindmap_node.

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?

Explains beforeId ordering versus append and constrains the operation to shape nodes, but does not state when to prefer this over update/reparent siblings or any when-not conditions.

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

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

The annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations by labeling the tool Experimental and warning that using it on an existing node can create a duplicate link.

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

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

The description is two tight sentences with no wasted text. The experimental warning and the core action are front-loaded, followed immediately by the key alternative.

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

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

The tool has complete schema coverage, annotations, and an output schema, so the description does not need to explain parameters or return values. It covers purpose, experimental status, and the main duplicate-link pitfall, though it could say slightly more about the create-vs-move boundary.

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 parameters including folderId, targetId, type, index, and workspaceId. The description does not add syntax or meaning beyond what the schema provides, so the baseline score 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?

The description states a specific verb and resource: adding a doc, tag, or collection link under an AFFiNE organize folder. It also explicitly distinguishes the tool from move_organize_node, so an agent can select it correctly without opening sibling schemas.

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

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

The description gives a direct usage rule: use move_organize_node for an existing link node instead of creating a duplicate link. This names the alternative and the condition that selects it, leaving little ambiguity about when to use add_organize_link.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, so safety is covered; the description adds a genuinely non-obvious behavioral fact: inapplicable style fields are echoed back in a response 'ignored' list. It stops short of noting that the operation is non-idempotent (repeated calls create duplicates) or what permissions/docId scope are needed.

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

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

Four short sentences, front-loaded with the core action, then element capabilities, use case, and the ignored-field caveat. No filler, though the parenthetical '(mirrors update_surface_element)' is slightly cryptic without direct routing language.

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

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

The tool has 31 parameters and an output schema; the description defers parameter specifics to the (fully documented) schema and to the output schema for the 'ignored' list, which is appropriate. Missing is any note that this is a non-idempotent create (duplicate calls duplicate elements) or how docId/workspaceId must line up.

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 earns one more by explaining connector binding semantics ('draw arrows between shapes (by id) or between absolute points') and which style families apply per element type, which reinforces how sourceId/targetId vs sourcePosition/targetPosition are chosen.

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

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

Names a specific verb and resource ('Add a shape, connector, text, or group to the AFFiNE edgeless canvas surface') and enumerates the element kinds, so an agent immediately knows the scope. It also implicitly separates itself from update_surface_element by noting the 'ignored' report 'mirrors update_surface_element'.

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 for building diagrams programmatically' gives a context cue, but there is no explicit when-not guidance or directive such as 'to modify an existing element use update_surface_element' / 'to inspect use list_surface_elements'. The routing to siblings is left to be inferred from the mention of the mirror behavior.

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 safety profile: readOnly=false, destructive=false, openWorld=true, idempotent=false. The description adds useful behavioral context beyond annotations: it may create a workspace tag option if missing and stores tags in workspace metadata. It does not contradict 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?

The description is two sentences and front-loads the core action. Every clause earns its place by adding the auto-creation side effect and the storage location.

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

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

Given an output schema, full parameter schema coverage, and annotations, the description is nearly complete. It covers the key mutation side effect and storage behavior, though it could mention permissions or workspace context requirements.

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 docId, tag, and workspaceId semantics. The description adds only high-level context (workspace tag, document) and no additional parameter syntax or format details beyond what the schema provides.

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

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

The description states a specific verb and resource: attach a workspace tag to a document. It also distinguishes the operation by noting automatic workspace-tag creation when needed, which separates it from siblings like create_tag or remove_tag_from_doc.

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

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

The description implies when to use it by describing the attach operation, but it does not explicitly name alternatives such as remove_tag_from_doc, create_tag, or list_tags, nor does it state exclusions. Usage is inferable but not actively guided.

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, non-destructive, and openWorld behavior, so the safety profile is covered. The description adds meaningful scope beyond annotations by naming the specific fidelity risks it examines, giving the agent a clearer sense of what is checked.

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

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

The definition is a single front-loaded sentence with no filler. It efficiently conveys the inspection target and risk categories.

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, annotations cover behavior, and parameter documentation is complete. The main remaining gap is the lack of explicit routing guidance relative to export_with_fidelity_report, but otherwise the description is sufficient for this read-only analysis 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?

Schema description coverage is 100%, and both docId and workspaceId are documented in the schema. The description does not add parameter-level guidance beyond the schema, so the baseline 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?

The description states a specific verb ('inspect'), resource ('document'), and concrete inspection targets (markdown export fidelity risk, unsupported AFFiNE block flavours, risky content paths). It clearly distinguishes a fidelity-inspection tool from export tools, though it does not explicitly contrast with the sibling export_with_fidelity_report.

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 'Inspect a document for markdown export fidelity risk' implies a pre-export or diagnostic use case, but it never states when to call this instead of export_with_fidelity_report or export_doc_markdown. No explicit when/when-not guidance or prerequisites are provided.

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 profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description is not required to restate safety. But it adds almost nothing behavioral: it name-drops "strict validation" without saying what strict rejects or that it defaults to true, gives no hint that appends are non-idempotent and can duplicate blocks, and says nothing about revision checks or the failure modes the 40-param surface implies.

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 padding, so nothing is wasted. The parenthetical is slightly vague filler, but the text is compact and the primary action leads.

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 40-parameter mutation tool with nested objects, edgeless-canvas geometry, and many overlapping siblings, one sentence is far short of complete: an agent gets no routing guidance, no sense of the edgeless-vs-document distinction, and no warning about strict-mode rejections. An output schema does exist, so return values need not be described, but the selection and behavioral context is largely absent.

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 of the 40 parameters carries substantive inline documentation, so the baseline of 3 applies. The description contributes only the high-level notion of canonical types/legacy aliases, placement, and strict validation; it adds no semantics for any individual parameter beyond what the schema already states.

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

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

The verb+resource pair ("Append document blocks") is unambiguous and the parenthetical adds that canonical types, legacy aliases, placement, and strict validation are involved. It never distinguishes itself from nearby siblings such as append_markdown, append_semantic_section, add_surface_element, or create_doc_from_markdown, 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 statement of when to reach for this tool versus the many alternative append/insert tools in the sibling list. No prerequisites, no exclusions, no note about document mode vs edgeless canvas, which the schema clearly supports.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description contributes the useful non-obvious conversion trait that $$...$$ and $...$ become native equations. It says nothing about what 'strict' mode changes, how placement affects the write, or the revision-conflict behavior implied by expectedRevision.

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 target, with the equation-conversion note as a compact second clause. 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 values need not be explained. Still, for a 6-parameter mutation tool with a nested placement object and an undocumented 'strict' flag, the description leaves real gaps about positioning and strictness that an agent must guess at.

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 83%, so the schema already documents docId, markdown, workspaceId, and expectedRevision in detail. The description adds only markdown-body syntax behavior, not parameter meaning; the nested placement object and the 'strict' flag remain unexplained by both description and schema.

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

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

States a specific verb and resource ('Append markdown content to an existing AFFiNE document'), which clearly separates it from create_doc_from_markdown and replace_doc_with_markdown by the word 'append'. However, it never names those siblings or explains the append-vs-replace distinction explicitly.

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

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

There is no guidance on when to choose this over append_block, replace_doc_with_markdown, or create_doc_from_markdown, and no prerequisites or exclusions. The only implied usage is that the target document must already exist.

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

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

Annotations already declare that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds useful append semantics (heading-based insertion, native block composition), but it does not disclose permissions, duplicate-heading behavior, or side effects beyond what annotations and schema 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?

The definition is a single front-loaded sentence with no filler. It states the action and mechanism immediately, leaving details to the rich schema and 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?

The tool is moderately complex with eight parameters, full schema coverage, an output schema, and annotations covering mutation safety. The description is minimal but sufficient because the schema handles parameter and return details; only finer behavioral nuances like duplicate-section handling are 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%, so all eight parameters are already documented. The description reinforces that sectionTitle and native block composition are central, but it does not add syntax, formatting, or behavioral detail beyond the schema.

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

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

The description gives a specific verb ('Append') and resource ('semantic section') scoped to an existing AFFiNE document, and notes the heading-title/native-block mechanism. It is clear enough to distinguish from generic block or markdown appends, though it does not explicitly name the sibling alternatives it replaces.

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

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

There is no explicit guidance on when to use this tool instead of append_block, append_markdown, create_semantic_page, or other document-editing siblings. The phrase 'existing AFFiNE document' implies a context but does not state exclusions or routing conditions.

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

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

The destructiveHint annotation already declares the safety profile, but the description adds meaningful context: the operation is permanent, applies only to already-deleted blobs, and requires prior confirmation. It stops short of describing whether the release is reversible or what errors occur on mismatched confirmation.

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

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

Two sentences, front-loaded with the action and scope, followed by the destructive-use caution. Every clause earns its place with no repetition or 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?

With an output schema, full parameter descriptions, and rich annotations, the description supplies the essential missing nuance: permanence and the confirmation precondition. The only gap is not routing the agent away from delete_blob/upload_blob in sibling-heavy context.

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

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

Schema coverage is 100%, and the schema already explains workspaceId and the exact-match requirement for confirmWorkspaceId. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 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: permanently release blobs that were already marked deleted, scoped to a workspace. The phrase 'already marked deleted' implicitly distinguishes it from delete_blob (which presumably performs the marking), but it never names that sibling explicitly.

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

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

Provides a clear precondition and caution: use only after confirming the deleted blobs are no longer needed, and it must be destructive cleanup. It does not explicitly contrast with delete_blob or upload_blob, so the exclusion guidance is implied 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 state readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is largely covered. The description adds useful scoping ('value from a document') but says nothing about what happens when the property is absent, whether clearing is reversible, or whether workspace context is required — all relevant for an openWorld, non-idempotent 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?

A single front-loaded sentence with no filler; the parenthetical clarifies the property parameter efficiently. It could be slightly more informative without becoming verbose, but nothing is wasted.

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

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

An output schema exists, so return values need not be described. However, an agent still lacks the sibling-routing information and workspace-scoping semantics needed to invoke this confidently alongside set_doc_property and delete_custom_property.

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

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

Schema coverage is only 33%, and the description only reinforces the one parameter the schema already documents ('property by id or name'). Neither docId nor workspaceId is explained in the description, so it fails to compensate for the low schema coverage on a third of the inputs.

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

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

The description uses a specific verb ('Remove') and a specific resource ('a custom property value from a document'), so an agent knows the operation without opening the schema. It does not, however, differentiate itself explicitly from siblings like set_doc_property or delete_custom_property, which sound closely related.

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

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

There is no guidance on when to use this instead of set_doc_property, list_doc_properties, or delete_custom_property. The distinction between clearing a per-document value and deleting a property definition globally is left entirely to inference, which is a real risk given those 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 it is a mutating (readOnlyHint=false), non-idempotent, non-destructive, open-world operation. The description adds what actually gets constructed (starter schema, kanban view, starter rows), which is real value, but it does not warn that repeated calls likely create duplicate databases or explain the stale-write guard implied by expectedRevision beyond the schema text.

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, front-loaded with the action and immediately followed by the concrete presets and artifacts produced. No filler, though sentence two is essentially a feature list that could carry one clarifying clause about when to choose this 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a creator tool with nested placement parameters and a revision-based concurrency guard, the description omits the duplicate-creation caveat and the write-ordering behavior an agent needs to invoke it safely.

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 seven parameters including the placement object and expectedRevision are already documented inline. The description only echoes the enum presets and the default starter-row behavior, adding no syntax, precedence, or interaction detail beyond the schema.

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

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

States a specific verb and resource: 'Create a ... AFFiNE database/data-view', and narrows it to declarative-intent composition with named presets. That is enough to distinguish it from row/column-level siblings like add_database_row or add_database_column, though it never names an alternative sibling explicitly.

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

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

Usage is only implied by 'from declarative intent' plus the two preset names. It does not say when to prefer this over create_doc, instantiate_template_native, or manual add_database_column/add_database_row workflows, nor any prerequisites such as creating/reading the doc first.

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 profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower. The description adds real value by naming what is mutated ("workspace sidebar metadata") and what is not (documents), but says nothing about permissions, duplicate-name behavior, or whether rules are applied retroactively.

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

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

Two sentences, front-loaded with the action and scope, zero filler. The non-document clarification is placed immediately after the core statement where it matters most.

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 plus a fully documented schema cover parameters. What remains thin is the relationship to update_collection_rules / add_doc_to_collection and any setup assumptions, but for a simple create call the description is nearly sufficient.

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

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

Schema description coverage is 100% and the nested filter/operator unions are thoroughly documented in the schema. The description only echoes "optional rules" and adds no semantics (e.g., what the allow-list means or how match:any interacts with filters), 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 ("Create a new AFFiNE sidebar collection with optional rules") and adds a negative scope clause ("does not create documents") that separates it from create_doc/create_semantic_page. It does not explicitly distinguish itself from update_collection, delete_collection or add_doc_to_collection, but the purpose itself is unambiguous.

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

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

There is no when-to-use guidance: nothing says use this first and then add_doc_to_collection, nor when to prefer update_collection over re-creating. The "does not create documents" line clarifies scope but is not a usage rule, so the agent must infer the workflow from sibling names.

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

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

The annotations already disclose that this is a non-readonly, non-idempotent, non-destructive, open-world write. The description adds useful context by saying it writes collaboration state and requires an existing document, though it does not cover side effects such as mention notifications or 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?

The description is two tight sentences with no wasted wording. It front-loads the core action and immediately follows with the sibling-routing guidance.

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

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

Given the full schema coverage, existing output schema, and annotations that cover the safety profile, the description provides enough context for correct invocation. No critical agent-facing detail is missing.

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 input schema already explains every parameter in detail. The description adds no parameter-specific syntax or constraints beyond what the schema provides, which is appropriate but not enriching.

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

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

The description states a specific verb and resource: creating a new comment on an existing document. It also explicitly distinguishes this from update_comment, which is the closest sibling action.

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

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

It gives a clear usage condition and a direct alternative: use this tool to create a new comment, and use update_comment when editing an existing comment. This leaves little ambiguity for tool selection.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that a propertyId is returned for chaining, but says nothing about duplicate-name behavior (relevant given idempotentHint=false) or permission requirements for workspace-wide changes.

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

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

Two sentences, front-loaded with the action and scope, followed by the return contract. No filler and nothing redundant.

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

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

An output schema exists, so return values needn't be explained, though naming propertyId is a nice touch. However, for a mutating create tool in a large sibling set, the description omits prerequisite context (how it relates to set_doc_property/list_doc_properties/delete_custom_property) and the meaning of the unlabeled workspaceId parameter.

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 75%, and the description restates the type enumeration already declared in the schema enum. The undocumented parameter, workspaceId, is not clarified in the description either — it's unclear whether workspaceId is optional or how the workspace-wide scope is resolved when it's omitted.

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 workspace-wide custom property definition") and scopes it with the allowed value types and the returned propertyId. The workspace-wide scope implicitly distinguishes it from doc-level operations like set_doc_property, but the sibling create/delete/list property tools are never named.

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, no prerequisite (e.g., that a definition must exist before set_doc_property can be used), and no mention of when NOT to use it. The only guidance is implied by "workspace-wide" and the existence of delete_custom_property.

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 safety profile (not read-only, not destructive, not idempotent, open-world), so the description does not need to repeat it. The description adds useful behavioral detail: content is stored as one paragraph, and parentDocId/folderId cause immediate sidebar-tree linking or folder placement. It does not discuss creation of duplicate docs on repeated calls, but the non-idempotent annotation covers that.

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?

Well-structured and front-loaded: core action first, then the sibling alternative, then parameter-specific sidebar behavior. Every sentence contributes, though the parentDocId and folderId sentences could be slightly tighter and arguably mirror what is already in the schema.

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

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

Given the output schema and rich annotations, the description covers what an agent needs to choose and invoke this tool correctly: plain-text limitation, sibling alternative, and sidebar placement effects. It does not explain return shape or failure conditions, but those are covered by the output schema and annotations.

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 every parameter, including the plain-text/paragraph behavior and the sidebar semantics of parentDocId and folderId. The description adds no parameter guidance beyond what the schema already says, 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 ('Create a new AFFiNE document') and immediately distinguishes it from the nearest sibling, create_doc_from_markdown, by contrasting plain-text content with structured Markdown support.

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 routes the agent: use this tool for plain-text single-paragraph content, and use create_doc_from_markdown for headings, lists, links, and code blocks. It also clarifies the sidebar consequences of parentDocId and folderId, so the agent knows what placement behavior to expect.

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

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

Annotations already declare readOnly=false, destructive=false, and openWorld=true, so the safety profile is covered. The description adds valuable beyond-schema behavior: the Markdown is converted into native blocks and $$...$$ / $...$ equations are preserved. It does not mention required permissions or side effects on a parent doc.

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

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

Two tight sentences with the core action and equation caveat front-loaded, followed by the placement options. No wasted prose.

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 the create-and-import behavior is covered. However, `strict` semantics and workspace/permission preconditions are absent, which matters for a mutating, open-world 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?

Schema coverage is 67%, and the description mostly restates what the schema already documents for parentDocId, folderId, and markdown. The `strict` flag, which materially changes parsing behavior, is undocumented in both the schema and the description.

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

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

States a concrete verb (create) and resource (AFFiNE document) plus the distinctive mechanism: importing Markdown as native blocks, including equation handling. It is clear, but it never names the sibling alternatives it differs from (create_doc, create_semantic_page, append_markdown, replace_doc_with_markdown), so differentiation is left implicit.

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

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

The second sentence gives conditional guidance for two parameters (use parentDocId to embed, folderId to place), but that is parameter selection, not tool selection. There is no statement about when to use this instead of create_doc or append_markdown, and no exclusions.

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-readonly, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds two genuinely useful facts the annotations don't carry — the 'Experimental' status and the fact that document content is untouched — but says nothing about permissions, failure modes, or what duplicate names do.

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 front-loaded sentences with no filler; the experimental caveat and the scope boundary each earn their place. Slightly abrupt but nothing is wasted.

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

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

With a full output schema and complete parameter documentation, the description only needs to frame purpose and scope, which it does. The remaining gap is not relating this tool to list_organize_nodes, move_organize_node, or rename_folder for follow-up operations.

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 name, index, parentId, and workspaceId semantics are already documented in the schema, including the AFFINE_WORKSPACE_ID fallback. The description mentions no parameters at all, 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 ('create an AFFiNE organize folder node in the sidebar tree') and immediately bounds the effect ('only changes sidebar organization, not document content'). That contrast is what separates it from create_collection or create_doc, though it never names those siblings explicitly.

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

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

Usage is implied rather than stated: the agent can infer this is for sidebar tree organization only. There is no explicit guidance on when to prefer a folder over a collection, nor prerequisites such as needing a parent from list_organize_nodes.

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 profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the description only needs to add what they don't cover. It does: return identifiers, the negative scope (no document, no sidebar link), and the BlockSuite layout limitation (down/up unsupported). It omits permission requirements and whether concurrent edits are guarded beyond the optional expectedRevision note.

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 action and scope, followed by return value, constraint, and excluded side effects. No filler and nothing repeated from the schema beyond the one exception the description must explain.

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 spelled out, and the safety profile is covered by annotations plus the excluded side effects. The gap is parameter documentation: for an 8-parameter mutation at 13% coverage, x, y, style, and workspaceId are unexplained, so the description under-serves the schema's complexity.

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

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

Schema description coverage is only 13% — just expectedRevision — so the description must compensate for seven undocumented parameters. It clarifies the layout domain (right/left/balance only, down/up rejected by BlockSuite) but says nothing about x/y positioning, style's 1-4 meaning, or workspaceId. Six of eight parameters remain semantically opaque.

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

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

States a specific verb and resource ("Create a native AFFiNE mindmap with one root shape in an existing document") and bounds the scope to a single root shape in a pre-existing doc. It also names the downstream sibling (add_mindmap_node) that consumes the returned ids, so an agent can place it in the workflow 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?

The phrase "in an existing document" plus "Does not create a document or sidebar link" routes the agent to the doc-creation tooling first, and "Returns mindmapId/rootId for add_mindmap_node" establishes the follow-on call. It stops short of naming create_doc explicitly as the prerequisite alternative, which keeps it from 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 non-readOnly, non-idempotent, non-destructive, open-world, so the safety profile is covered. The description adds nothing beyond a restatement of intent: it does not say what happens when pageType is omitted, whether defaults seed sections, whether a parent is required, or how it resolves workspace scope. For a non-idempotent write with an open-world hint, that is a real gap.

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

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

A single front-loaded sentence with no filler, verb and resource first. It is efficient, though the brevity borders on under-specification rather than tightness.

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

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

An output schema exists and the schema documents all five optional parameters, so return values and inputs need not be re-explained. But with zero required parameters and a non-idempotent write, the description should clarify defaults, override behavior, and workspace resolution; it leaves those to inference.

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 every parameter is documented in structured fields and baseline 3 applies. The description's phrases 'section structure' and 'native block composition' loosely gesture at sections and pageType but add no format, precedence, or interaction detail (e.g., how explicit sections override pageType defaults) beyond the schema.

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

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

States a specific verb and resource ('Create an AFFiNE-native page') and adds a distinguishing qualifier about section structure and native block composition, which separates it from a plain doc-creation tool. It never names the sibling it is contrasted with (create_doc, instantiate_template_native), so the differentiation stays implicit.

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

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

There is no when-to-use guidance and no mention of alternatives among the many nearby creation tools (create_doc, create_doc_from_markdown, instantiate_template_native, append_semantic_section). The agent must infer that this is the structured-page path versus the markdown or template path.

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 mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description usefully adds the 'registry entry only, no attachment' scope. However it never says what happens if the tag already exists — a critical behavior for a create tool flagged as non-idempotent.

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

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

Two tight sentences: the action first, then the disambiguation. Every clause earns its place and there is 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?

Output schema exists so return values needn't be described, and annotations cover the safety profile. For a simple two-parameter create tool the only real missing piece is duplicate-tag handling, which keeps it just below full completeness.

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 both parameters (tag, workspaceId) are fully documented in the schema. The description's 'workspace-level' phrasing adds marginal context about the workspaceId, but nothing about format or constraints beyond the schema. Baseline 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+resource ('Create a workspace-level tag entry') and immediately distinguishes it from the sibling add_tag_to_doc, which is exactly the confusion an agent could have. No ambiguity about what gets created.

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 states the when-not ('This does not attach the tag to a document') and names the alternative tool to use instead. This is the strongest possible routing guidance with no inference needed.

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=false, readOnlyHint=false, and non-idempotency, so the safety profile is covered. The description adds genuine context beyond that: creation also produces an initial document and the result is visible in the UI. It does not say whether duplicate names are rejected, what permissions are required, or what the initial document contains.

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 padding. The parenthetical "(accessible in UI)" is slightly ambiguous — unclear whether it modifies the workspace or the initial document — but the overall length is well matched to the task.

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 describe return values, and annotations cover the safety profile. However, for a creation tool with an undocumented side effect (initial document), it should say more about what that document is and any naming constraints.

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 two parameters, both fully described in the schema, so the baseline is 3. The description adds no format, length, or uniqueness constraints for `name`, nor does it explain how `avatar` is interpreted as emoji versus URL.

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 new workspace") and adds a distinguishing detail: it also creates an initial document. An agent can identify the operation without opening the schema. It stops short of naming how it differs from the sibling create_workspace_blueprint.

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 alternatives such as create_workspace_blueprint, nor any prerequisite or exclusion guidance. The agent must infer selection criteria 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 establish this is a non-read-only, non-destructive, non-idempotent operation, so the safety profile is covered structurally. The description adds that this is a composite of multiple folder creations, hinting at multi-step behavior, but it does not say whether the operation is atomic, what happens if a child folder name collides with an existing one, or what permissions are required.

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

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

Two short sentences, zero filler, with the resource definition front-loaded and the wrapper relationship placed immediately after where it is most useful for disambiguation.

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 convenience wrapper with full schema coverage, an output schema present, and annotations covering the safety profile, the description supplies what an agent needs to select and invoke it. The only shortfall is the absence of failure/collision semantics for a tool that creates several folders in one call.

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 three parameters (workspaceId, rootFolderName, childFolderNames) are already documented, including the AFFINE_WORKSPACE_ID fallback. The description only restates the required/optional split implied by the schema, adding no new syntax, naming-constraint, or ordering semantics.

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 (Create) plus the resource (AFFiNE organize folder blueprint) and immediately defines the shape: one root folder plus optional children. The second sentence explicitly positions it as a wrapper around create_folder, so an agent can distinguish it from the sibling without inspecting either 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?

Calling it a 'wrapper around create_folder' implies the choice (use this for multi-folder setup, plain create_folder for a single folder), but the description never states that when-to-use explicitly, nor does it mention anything about when not to use it (e.g., when child folders already exist or when folders must be created with differing settings).

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 openWorldHint, so safety is covered by structured data. The description adds genuinely new context beyond that: this is a credential/identity check that should precede other workspace or document calls, which no annotation conveys. Minor gap: it does not say what happens when unauthenticated.

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 identity of the return value is front-loaded and the usage guidance 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?

With an output schema present (so return shape needn't be described), rich annotations, and no parameters, the description supplies all an agent needs: what is returned and when to call it. Nothing material is missing for a tool of this complexity.

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

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

The tool takes no parameters, so per the baseline this scores 4. There is nothing for the description to disambiguate, and it correctly implies a zero-argument call.

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 ('Return the currently authenticated AFFiNE user profile'), which is unambiguous and distinct from the neighboring sign_in (authentication) and update_profile (mutation) tools. An agent can identify exactly what this tool yields 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 prescribes the use case: 'verify credentials before workspace or document operations,' which gives the agent a concrete precondition workflow. It stops short of naming alternatives or exclusions (e.g., when not to call it), so it lands just below the top band.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavioral detail: deletion is recoverable by default and only permanent when bypassing recovery. It stops short of mentioning the confirmKey safeguard, which would make it a 5.

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

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

Two short sentences, the core action front-loaded and the conditional flag guidance second. No filler, though the second sentence could be slightly tighter.

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

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

Output schema exists and all four params are documented, so the description needn't explain return values. The recoverable-vs-permanent semantics are covered; the only gap is the absence of the confirmKey requirement and sibling differentiation.

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 already explains permanently ('permanently delete instead of marking it deleted') and confirmKey. The description's 'bypass recoverable deletion' phrasing reinforces the default-versus-permanent distinction but adds little 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?

Specific verb+resource ('Delete a blob') scoped to AFFiNE workspace storage, so it is clearly distinguishable from cleanup_blobs by intent. It does not explicitly name the sibling, keeping it below 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 hints at when to use permanently=true ('only when the blob should bypass recoverable deletion'), which is useful guidance for the flag. However, it never says when to call delete_blob vs cleanup_blobs, nor notes the confirmKey prerequisite, so usage context is only implied.

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

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

Annotations already flag destructive=true and non-idempotent, and the description adds substantive behavior: returns snapshots of removed content, unlinks from the parent's sys:children, cascades descendants by default, prunes surface connectors on request, and hard-refuses affine:page. This goes well beyond what the annotations disclose.

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 dense sentences, front-loaded with the core action, then the default/flag semantics, then the refusal-plus-alternative. No filler; each clause routes a decision.

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, yet the description still signals the snapshot return, and it covers the destructive default, connector scope, and the affine:page guard. For a destructive mutation with 6 params, nothing an agent needs is missing.

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 genuine meaning: the re-parenting rationale for deleteChildren=false and the surface-connector scope of pruneConnectors. That is value the schema itself does not carry.

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 by id') with a clear return payload ('return snapshots of the removed content'), and explicitly distinguishes itself from delete_doc by refusing affine:page. An agent can pick the right tool 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 explicit when-to-use branching per flag: default cascades descendants, deleteChildren=false for re-parenting via orphaning, pruneConnectors=true for connector cleanup. It also names the alternative for whole-doc deletion, closing the loop.

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=false and openWorldHint=true, so the bar is lower, yet the description still earns credit by defining the destructiveness boundary: metadata is destroyed, referenced documents are preserved. It stops short of stating irreversibility 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 redundancy, with the destructive scope clarification front-loaded right after the action statement.

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 the safety profile and an output schema present, the description needs only the action and the blast radius, both of which it supplies. Missing only auth/permission preconditions for a workspace-scoped destructive call.

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 inline (including that collectionId comes from list_collections or create_collection), so the baseline of 3 applies; the description adds no parameter-level detail beyond what the schema already says.

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 an AFFiNE sidebar collection') and immediately scopes the effect ('removes the collection metadata but does not delete the documents it referenced'), which separates it from delete_doc and trash_doc in the sibling list.

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 scope note implies when this is the right call (removing a container, not its contents), but there is no explicit when-to-use guidance and no named alternative such as remove_doc_from_collection or update_collection for the case where the caller only wants to detach items.

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