AFFiNE MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v3.2.1
Disambiguation4/5
Most tools have clearly distinct purposes (workspaces, docs, tags, databases, canvas, comments, collections, folders, properties, icons, user, blobs, notifications), and descriptions explicitly distinguish near-overlaps like get_doc vs read_doc and find_doc_by_title vs search_docs. A few pairs (update_surface_element vs update_edgeless_block) could cause confusion, but their descriptions are clear enough.
Naming Consistency4/5
The overwhelming majority follow a consistent verb_noun snake_case pattern (list_, get_, create_, update_, delete_, append_, etc.). Minor deviations like 'current_user' (a noun phrase rather than verb-first) and a few multi-word descriptive names (analyze_doc_fidelity, instantiate_template_native) break the pattern slightly but do not hinder readability.
Tool Count1/5
At 96 tools, this is an extreme count, far exceeding the 'well-scoped' guideline of 3-15 tools. Even accounting for AFFiNE's broad feature set, the sheer number imposes a high selection burden and increases the risk of misselection, making the tool surface unwieldy.
Completeness4/5
The server covers an impressively broad range of AFFiNE domains with full CRUD or lifecycle operations for workspaces, docs, tags, databases, canvas elements, comments, collections, folders, properties, icons, blobs, and notifications. Minor gaps exist (e.g., no full-text search, no explicit move-doc-to-folder tool, no workspace member management), but the core workflows are well covered.
Average 4.1/5 across 96 of 96 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 117 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not disclose whether updates are partial or full, what errors may occur, or any side effects. The annotations already indicate it is a non-read-only, non-idempotent, non-destructive operation, but the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence, making it concise and free of fluff. However, it is so brief that it edges toward under-specification rather than efficient communication, though it does earn its place by stating the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, and the schema, annotations, and output schema fill in some gaps. Yet the description leaves out important contextual details like whether the update is partial (only provided fields) and what happens to unspecified settings. This is a minimal viable description, but it could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for all parameters (id, public, enableAi) with clear descriptions, so the baseline of 3 applies. The tool description does not add any additional meaning or explanation about the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action (update) and target (workspace settings), but it is vague and does not specify which settings. It does not differentiate from sibling tools like create_workspace or delete_workspace, and the phrase 'Update workspace settings' is little more than a restatement of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or situations where another tool (create_workspace, delete_workspace) would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond the literal export action; it does not mention what content is included/excluded, whether frontmatter is optional, or any side effects. It essentially restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant content. It is front-loaded and efficient, earning its place with a clear statement of purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has annotations plus an output schema, but the description lacks usage context and fails to differentiate from sibling export tools. It also leaves includeFrontmatter unexplained, making it only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents docId and workspaceId with descriptions, but includeFrontmatter has no description. The tool description provides zero parameter semantics and does not clarify the boolean's effect, leaving a gap in understanding the function.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Export), resource (AFFiNE document content), and format (markdown). However, it does not distinguish from the similar sibling tool export_with_fidelity_report, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like export_with_fidelity_report or read_doc. No exclusions or prerequisites are mentioned, leaving the agent without direction for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint: false) and non-destructive behavior. The description adds no additional context about partial updates, permissions, or effects, merely restating the title.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff. It is appropriately brief for a simple tool, though it could have included more useful guidance without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of a similar sibling tool (update_profile) and the availability of an output schema, the description lacks essential usage context. It does not clarify what settings are covered or why this tool differs from alternatives, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (single 'settings' parameter with nested object), so the schema fully documents the parameter. The description adds no extra semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates user settings and preferences, using a specific verb and resource. However, it does not differentiate from sibling tools like update_profile, which could also update user-related data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_profile. There is no mention of context, exclusions, or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description describes a destructive operation — 'Replace the main note content' — but the annotations declare destructiveHint=false, which is a direct contradiction. The description also fails to disclose that existing content will be overwritten and lost, and it does not mention the behaviors of strict or allowEmpty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant words. It front-loads the verb 'Replace' and immediately communicates the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description is too minimal for a tool with 5 parameters. It does not explain the crucial behavioral consequences (e.g., data loss), the meaning of 'strict', or the implications of 'allowEmpty'. The contradiction with the annotations further undermines its completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80% (4 of 5 parameters have descriptions), so the baseline is 3. The description does not add any meaning beyond the schema; the 'strict' parameter remains entirely undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Replace' and clearly identifies the target as 'the main note content of a document' with 'markdown content.' This distinguishes it from sibling tools like append_markdown (which adds) and create_doc_from_markdown (which creates a new document).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as append_markdown or create_doc_from_markdown. It does not mention prerequisites, exclusions, or any context that would help an agent choose this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds no additional behavioral context, such as ordering, duplication on repeated calls, or prerequisites. It is consistent with annotations but contributes minimally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and optional section positioning (afterSectionTitle), the description is minimal. However, the schema fills in parameter semantics and the output schema likely covers returns, so the description's brevity is partially compensated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have descriptions in the schema (100% coverage), so the description doesn't need to explain them. The brief phrase 'by heading title and native block composition' aligns with schema but adds no new detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (append), resource (semantic section to an existing AFFiNE document), and method (by heading title and native block composition). It distinguishes from creation tools but doesn't explicitly compare to append_block or append_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like append_markdown or append_block. It doesn't state exclusions or use cases, leaving the agent to infer 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint false), non-destructive (destructiveHint false), and non-idempotent (idempotentHint false). The description adds minimal context with 'AFFiNE-native' and 'native block composition', but does not disclose additional behavioral traits such as side effects on workspace structure, permissions required, or how sections are created. This aligns with the annotations and adds slight value, but not enough for a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the primary action ('Create an AFFiNE-native page') and adds a brief qualifier. Every word contributes, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, an enum, and a specific semantic purpose, the description is too thin to fully inform selection and invocation. It does not explain the significance of pageType templates, the role of sections, or when to use this instead of create_doc or append_semantic_section. The schema provides parameter details, but the description does not provide the higher-level context needed for appropriate use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add any extra meaning about the parameters beyond what the schema already provides. It mentions 'intentional section structure' which loosely maps to sections/pageType, but does not elaborate on how parameters interact or any parameter-specific constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an AFFiNE-native page, and the phrase 'intentional section structure and native block composition' indicates a structured page creation, distinguishing it from a plain doc creation. However, it never directly names sibling alternatives like create_doc, so it doesn't explicitly differentiate but is still specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as create_doc or append_semantic_section. The description provides no context about the intended scenario, no exclusions, and no mention of prerequisites or comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, but the description adds no extra behavioral traits such as side effects, failure modes, or default placement behavior. It merely states the action without disclosing anything beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence containing exactly the essential information: verb, object, and target. No redundant phrases or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has multiple parameters and a nested placement object, but the description only covers the core purpose. It does not mention optional placement, workspaceId handling, or usage context, yet the output schema exists so return value explanation is unnecessary. Adequate but minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, with the 'strict' parameter lacking a description. The tool description itself does not elaborate on any parameter, so it provides no added meaning beyond the schema. Baseline 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'append' with the resource 'markdown content' and target 'existing AFFiNE document', clearly distinguishing this from sibling tools like create_doc or replace_doc_with_markdown. It is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as append_block or create_doc. The description lacks context about conditions, prerequisites, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds no behavioral context such as permanence, cascading effects, or error conditions. It does not contradict annotations, but it adds no extra value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It clearly states the verb and object, making it appropriately concise for the simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema provides full parameter documentation, and the output schema covers return values, while annotations indicate destructive behavior. However, the description itself lacks an explicit statement about permanence or side effects, leaving some ambiguity for such a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are already documented with descriptions. The tool description adds no additional meaning beyond the schema, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'delete' and identifies the resource as 'a row from an AFFiNE database block'. This clearly distinguishes it from sibling row tools like add_database_row and update_database_row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there exclusions or prerequisites. The description simply states the action, leaving the agent to infer the appropriate context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the validation behavior against property type, which is useful. However, it does not disclose side effects (e.g., overwriting existing values, behavior on invalid property) despite openWorldHint=true, so it only partially covers behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and resource. Every word earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description lacks contextual details needed for reliable invocation: it does not mention the optional workspaceId, prerequisites (e.g., property must exist), or any failure behavior. openWorldHint=true increases the need for such context, which is not provided. This is inadequate for a tool with 4 parameters and 50% schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, with docId and workspaceId lacking descriptions. The description adds no new parameter semantics for these fields; it merely restates the 'property by id or name' and value validation already present in the schema. It fails to compensate for the undocumented workspaceId and docId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and identifies the resource ('a document's custom property value') and the mechanism ('property by id or name'). This clearly distinguishes it from sibling tools like clear_doc_property (which removes a property) and create_custom_property (which defines the property).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., the property must already exist) or contrast with clearing/creating properties. The usage context is only implied by the verb 'set', not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is established. The description adds useful context by specifying that it lists both workspace definitions and document values, but it does not disclose behavior like how workspaceId is handled when omitted, error conditions, or pagination. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundancy. It front-loads the action 'List' and immediately clarifies the scope, making it efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature, output schema presence, and clear annotations, the description is mostly adequate. However, with 0% parameter schema coverage and no usage guidance, it falls short of fully enabling autonomous correct invocation, especially regarding optional workspaceId behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It references 'workspace' and 'document,' which maps to workspaceId and docId, but it does not explicitly define each parameter's role, whether workspaceId is optional, or how the parameters interact. This leaves ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resources: 'workspace custom-property definitions' and 'a document's current values for them.' This distinguishes it from sibling tools like create_custom_property, set_doc_property, and clear_doc_property, which modify properties rather than list them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as set_doc_property or list_custom_properties. It does not mention prerequisites, exclusions, or scenarios where this tool is preferred over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating (readOnlyHint=false), non-destructive (destructiveHint=false) operation. The description adds value by explaining the behavioral consequence of using `parentDocId`—the doc becomes visible in the sidebar instead of being an orphan. This context goes beyond the annotations and enhances transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the primary purpose, and includes a practical tip without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core function and a key parameter, but it omits explanation of `strict` and doesn't clarify when to choose this tool over siblings. With an output schema present, return values are covered, but the missing parameter context and usage positioning leave gaps for a 5-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60%, leaving `title` and `strict` undocumented. The description only rehashes the `parentDocId` behavior already present in the schema, adding no new meaning. The ambiguous `strict` parameter is not explained, so the description fails to compensate for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new AFFiNE document and imports markdown content, which is a specific verb+resource. However, it doesn't explicitly distinguish this tool from siblings like `create_doc` or `append_markdown`, so it's clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides conditional usage guidance for `parentDocId`, explaining how to embed the new doc in the sidebar. But it doesn't explicitly state when to use this tool over alternatives like `create_doc` or `replace_doc_with_markdown`, so guidance is implied rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond the basic 'generate' action. It does not disclose whether the tool creates a new canvas element, how it affects existing content, or any side effects. Annotations already indicate it is a non-read, non-idempotent operation, so the description contributes little additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words or filler. It communicates the core purpose efficiently and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has five parameters, annotations, and an output schema, the description is minimally adequate. It states the purpose but lacks operational context such as how parameters like sub topics and markdownList interact, or what happens on creation. The schema and annotations cover structured aspects, but the description could be more complete for a create-type tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters have schema descriptions (100% coverage), so the description does not need to explain them individually. The description mentions 'markdown nested list', which loosely relates to markdownList, but it adds no meaningful parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a structured markdown nested list mindmap for AFFiNE edgeless canvas, combining a specific verb ('generate') with a distinct resource ('mindmap for AFFiNE edgeless canvas'). This distinguishes it from sibling tools like create_doc or add_surface_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: you would use this tool when you need to create a mindmap on the edgeless canvas. However, it provides no explicit when-to-use or when-not-to-use guidance, no alternatives, and no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, which cover most behavioral traits. The description adds that histories are 'timestamps,' but does not disclose details like ordering, pagination semantics, or what constitutes a history entry. It adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. Every word contributes to clarity, making it an excellent example of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists (so return values are covered), the description leaves key parameter semantics ambiguous, especially 'before' and 'workspaceId.' For a tool with 4 parameters, this description is too sparse to be complete for an agent deciding how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only 'take' has a description). The description's 'for a doc' hints at the required 'guid' but does not explain 'before' (likely a time filter) or 'workspaceId.' Low coverage in the schema means the description should compensate, but it largely fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'List doc histories (timestamps) for a doc.' It uses a specific verb ('List') and identifies the resource ('doc histories') with a clarifying parenthetical ('timestamps') and scope ('for a doc'). This distinguishes it from sibling tools like list_docs, which list documents themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description: it lists history for a doc. However, there is no explicit guidance on when to use this vs. alternatives, nor any exclusions or mentions of related tools. The description is self-explanatory but lacks strategic context for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the agent knows this is a non-idempotent write. The description adds only the `title` behavior, which is already documented in the schema for `cells`. It does not disclose side effects, return values, error conditions, or how openWorldHint manifests. Minimal added value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core action and a key usage tip. Every word earns its place; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7-parameter schema with full descriptions and an output schema, the description is adequate for selecting the tool. However, it offers little context about edge cases (e.g., what happens if a column doesn't exist, or the effect of `createOption`). The annotations and schema fill most gaps, but the description is thin for a mutation tool with openWorldHint=true.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a meaningful description (e.g., `createOption` defaults, `linkedDocId` behavior). The description adds no additional parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Batch update multiple cells on an existing AFFiNE database row.' It uses a specific verb ('update'), specifies the resource ('existing AFFiNE database row'), and adds a unique detail about updating the Kanban row title via `title`. This distinguishes it from sibling tools like add_database_row and delete_database_row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for updating an existing row, not creating or deleting one. However, it does not explicitly mention alternatives or exclusions (e.g., 'use add_database_row to create a new row'). The 'existing' wording implies the scope, but the guidance is not as explicit as tools that name sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds no further behavioral context, such as whether unspecified fields are preserved (partial update) or reset, or any authentication requirements. This leaves ambiguity about update semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It is appropriately sized for a simple tool and front-loads the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with complete schema and annotations, but the description omits important context about whether the update is partial or full replacement. This is a clear gap given that all parameters are optional, making update semantics critical for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both name and avatarUrl. The description itself does not add parameter details beyond the schema, so it holds at the baseline of 3, neither helping nor hindering parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the current user's profile information, using a specific verb and resource. It distinguishes from sibling tools like update_settings and current_user by targeting the profile specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the current user's profile needs updating, but does not explicitly state when to use it versus alternatives or any exclusions. There is no direct comparison with sibling tools like update_settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations, which already indicate a non-read-only, non-destructive mutation. It does not disclose whether the operation is reversible, how it affects existing rows, or any permission requirements, leaving the agent without additional operational insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two succinct sentences: the first states the primary action and target, and the second lists supported types. It is front-loaded with the core purpose and contains no wasteful or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, complete parameter descriptions, and annotations, the description is sufficient for understanding the tool's basic operation. It lacks details on side effects like default column values or impact on existing rows, but these are not critical given the structured data available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all seven parameters, so the baseline is 3. The tool description only reiterates the supported types already captured in the enum, adding no new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a column to an existing AFFiNE database block' with a specific verb and resource. It distinguishes itself from sibling tools like add_database_row by explicitly targeting columns, and it enumerates the supported column types, reinforcing the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a column needs to be added to an existing database, but it does not explicitly mention alternatives like add_database_row or provide when-not-to-use guidance. The context is clear, yet no exclusions or alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, non-idempotent operation. The description adds that it supports placement and strict validation, which provides some context beyond annotations. However, it does not describe side effects, error behavior, or ordering guarantees, so it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with 'Append document blocks', and contains no filler. Every phrase ('canonical types and legacy aliases', 'supports placement + strict validation') conveys key differentiating features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (37 params, nested objects), the schema provides exhaustive documentation, and an output schema exists. The description summarizes the core value proposition compactly, though it omits details like edgeless vs doc contexts and markdown parsing, which are captured in the schema. This is sufficient for an agent guided by schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description mentions canonical types/aliases, placement, and strict validation, but these are already covered in the schema (e.g., type's 'Legacy aliases remain supported', placement and strict properties). No additional meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends document blocks, and emphasizes canonical types, legacy aliases, placement, and strict validation. This distinguishes it from sibling tools like append_markdown (raw markdown) and append_semantic_section (semantic sections), even though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided. The description states what the tool does but does not contrast it with append_markdown, append_semantic_section, or update_edgeless_block. Users/agents must infer usage from the tool name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose write behavior (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds context about the output style (AFFiNE tokens, design system) but doesn't discuss side effects, permissions, or idempotency beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant content, making it highly concise and immediately readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with annotations and an output schema, the description provides sufficient context about the tool's purpose and output. It lacks explicit usage guidance against sibling tools, but the tool is simple and the schema fills in details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented with clear descriptions. The tool description itself adds no parameter-specific meaning beyond what the schema already provides, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description specifically states 'Create an AFFiNE document containing a rich interactive HTML/CSS dashboard widget' – a clear verb+resource+content type. It distinguishes from generic create_doc and similar specialized tools like create_mindmap_canvas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description only states what it does, not when to prefer it over create_doc or other creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal that the tool is not read-only, not destructive, and not idempotent. The description adds minimal behavioral context beyond the schema—it repeats the 'by id or name' detail but does not disclose what happens if the property does not exist, whether the operation is reversible, or what success/failure looks like. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that communicates the core function efficiently. It does not waste words, though it could include a bit more behavioral detail without becoming bloated. It is concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has an output schema, and the annotations cover basic safety traits. The description explains the main action and the property parameter. However, it lacks guidance on use cases vs. sibling tools, and the non-idempotent mutation nature could warrant more detail. It is complete enough for a minimal viable description but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'property' has a description). The description compensates slightly by repeating that the property can be specified by id or name, but it does not explain 'docId' or 'workspaceId'. Since the description must carry more weight for low-coverage schemas, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('remove') and the resource ('a custom property value from a document'), and adds the distinction 'by id or name' to disambiguate from sibling tools like delete_custom_property (which removes the property definition itself) and set_doc_property (which writes a value). This is a specific verb+resource combination that fully distinguishes the tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the clear use case: removing an existing custom property value from a document, as opposed to deleting the property definition. However, it does not explicitly state when not to use this tool or mention alternatives. The context from sibling names helps, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only, not idempotent, and not destructive. The description adds meaningful behavioral context by stating that creation includes an initial document accessible in the UI, which is not implied by the annotations or schema. However, it does not detail other side effects, but given annotations and output schema, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the primary action and resource while adding relevant context about the initial document. Every word serves a purpose, with no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, output schema present, annotations provided), the description is largely complete. It covers the core behavior and a notable side effect (initial document) but could optionally mention that no other workspace attributes are created initially. This minor gap is acceptable given the output schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (name and avatar). The description adds no semantic detail beyond what the schema provides, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new workspace'), and adds a distinctive qualifier ('with initial document (accessible in UI)') that specifies scope and differentiates it from other workspace-related tools like update_workspace or delete_workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as create_workspace_blueprint or update_workspace. It does not mention prerequisites, exclusions, or preferred scenarios, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing return fields (docId, title, direct URL, inTrash) and the metadata-based, fast search nature, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, dense sentences that front-load the core purpose and immediately convey key behavior and return values. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and comprehensive parameter schema, the description covers purpose, method, performance, and return fields. It slightly lacks explicit differentiation from the sibling find_doc_by_title, but remains sufficiently complete for a search tool with strong structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% description coverage for all 7 parameters with detailed meanings and defaults. The tool description adds no extra parameter semantics beyond what the schema already specifies, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource+scope: it searches documents by title using workspace metadata, and explicitly lists return fields. However, it does not distinguish itself from the similarly named sibling tool find_doc_by_title, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context by stating it is much faster than exporting each doc, implying a use case. But it does not explicitly mention when not to use it or name alternative tools like find_doc_by_title or list_docs, leaving usage boundaries vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context about starter schema, kanban view, and optional starter rows, which is useful. However, with annotations including openWorldHint=true and idempotentHint=false, the description does not explain potential side effects (e.g., modifying the target document or creating linked resources). It is not misleading, but it misses an opportunity to clarify non-obvious behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the core action and then lists key features. Every word adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the what and the presets, but it does not mention that a target docId is required, which is a critical prerequisite for invocation. The output schema exists, so return values are covered, but the description leaves the agent to infer the need for a host document from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, so the description carries no additional burden. It mentions 'optional starter rows' and 'presets', which aligns with seedRows and intent, but does not add meaning beyond the schema's already-descriptive parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Create') and its resource ('AFFiNE database/data-view') with a specific mechanism ('from declarative intent'). It also names the supported presets (task_board, issue_tracker), which distinguishes it from sibling tools that handle individual rows or document creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by mentioning the supported presets and optional starter rows, implying when to use it (for task boards or issue trackers). It does not explicitly exclude alternatives, but it provides enough context for a knowledgeable agent to select it over row-level or document-level tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive traits, so the description adds valuable context beyond them: it notes the O(n) scan behavior across all docs and mentions that each doc includes an inTrash flag. This gives the agent performance and output expectations not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no redundant information. It front-loads the core purpose, then adds context and a performance warning, with each sentence earning its place. No excessive detail or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description is mostly complete for a read-only listing tool. It defines the core concept and adds performance and output details, but it omits any explanation of the workspaceId parameter, leaving a minor completeness gap. Overall, it covers the essential context well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not mention the sole parameter workspaceId at all. While the parameter name is relatively self-explanatory, the description fails to clarify its role (e.g., whether it scopes the search to a specific workspace or defaults to all), leaving a gap that the description should compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find all documents') and a clearly defined resource ('orphan docs'), explicitly defining what qualifies as orphaned (no parent via embed_linked_doc, embed_synced_doc, or inline LinkedPage references). This clearly distinguishes it from sibling tools like list_docs or search_docs by focusing on parentless documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers a use case ('Useful for workspace hygiene') which implies when to use the tool, but it does not explicitly state when to prefer this over alternatives or provide exclusions. No comparisons to sibling tools are made, leaving the usage guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds useful behavioral detail by specifying the exact child types considered and the fields returned, which goes beyond what annotations provide. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, with the primary action and scope stated first, followed by the return fields. Every sentence adds value, and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple read-only operation with output schema and clear annotations, the description covers the essential behavior and result fields. The main gap is the undocumented workspaceId parameter, which prevents full completeness, but the overall context is sufficient for a basic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: docId has a description, but workspaceId is completely undocumented. The tool description does not mention workspaceId at all, leaving its purpose and necessity unclear. It only implicitly clarifies docId through the phrase 'parent doc,' which the schema already states. Thus the description fails to compensate for the missing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists direct children of a document in the sidebar, specifying exactly which child types are included (embed_linked_doc / embed_synced_doc blocks and inline LinkedPage references). It also lists the return fields (docId, title, URL, inTrash), making the purpose unambiguous and distinct from sibling tools like list_docs or get_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving immediate children in a document hierarchy, but does not explicitly state when to use this tool versus alternatives like list_workspace_tree or get_orphan_docs. It offers no exclusions or alternative tool references, so guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds a performance trait ('may be slow on large workspaces') and indicates return node details ('inTrash flag'), which are not covered by annotations. No contradiction exists, and the added context is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that front-load the purpose, then provide usage detail and a warning. There is no redundant filler, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and annotations are rich, the description adequately covers the tool's core behavior: tree structure, depth limiting, performance note, and node flag. The only minor gap is that workspaceId's role remains implicit, but overall completeness is strong for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, covering only 'depth,' while 'workspaceId' has no description. The description repeats depth's default but does not clarify the meaning or requiredness of workspaceId. It fails to compensate for the undocumented parameter, providing minimal additional value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Returns the full document hierarchy as a tree (roots → children → grandchildren).' This uses a specific verb ('returns') and resource ('document hierarchy'), and distinguishes it from sibling tools like list_docs or list_children by emphasizing the tree structure and full hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives usage context via the depth parameter and a performance warning ('loads all docs — may be slow on large workspaces'), but it does not explicitly state when to use this tool over alternatives like list_children or list_docs. The warning implies cautious use but lacks direct comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool may create a tag if needed and that it updates workspace metadata and attempts to sync document metadata. This adds useful side-effect context that is not captured by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the main action, and every sentence adds value. There is no filler or unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema coverage, annotations, and presence of an output schema, the description adequately covers the main behavior and side effects for a simple tool. It does not mention error scenarios or return values, but these are not essential given the tool's simplicity and the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters (100% coverage), so the description does not need to repeat them. The description adds minimal extra meaning beyond mentioning 'workspace tag', and does not clarify parameter formats or the workspaceId omission rule beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Attach') and clearly identifies the resource ('workspace tag to a document'), and it mentions creating the tag option if needed, which distinguishes it from sibling tools like create_tag and 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for attaching a tag to a document, but it does not explicitly state when to use it versus alternatives like create_tag or remove_tag_from_doc. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, and idempotent behavior. The description adds valuable context by specifying exactly what the inspection covers ('unsupported AFFiNE block flavours and risky content paths'), which goes beyond the safety profile. It does not describe output format or side effects, but those are covered by the output schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action and includes specific detail without any redundant or vague wording. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the existing output schema, and thorough annotations, the description covers the essential purpose and scope. Its only shortcoming is the lack of explicit connection to related export tools, which creates a slight ambiguity about the workflow context, but this does not impede basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both docId and workspaceId, achieving 100% coverage. The tool description adds no additional parameter-specific semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') and clearly identifies the resource ('a document') and the exact purpose ('markdown export fidelity risk'). It further specifies the scope by listing 'unsupported AFFiNE block flavours and risky content paths', which distinguishes it from sibling tools like export_doc_markdown or 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies an inspection use case before export but does not explicitly state when to choose this tool over alternatives such as export_with_fidelity_report. It provides no when-not-to-use guidance or mention of alternative tools, leaving the decision to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that it returns a propertyId, which is useful. It does not disclose side effects like duplicate handling or permission requirements, but annotations carry part of the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded and contains no fluff. It conveys the action, scope, types, and return value efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with an output schema and annotations, the description covers the essential purpose, types, and return value. It lacks explicit guidance on required workspaceId or error conditions, but the overall context is sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, with name and type already defined. The description adds the allowed values for type and implies workspaceId's role through 'workspace-wide'. It does not clarify icon or workspaceId beyond schema, so the added value is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and a clear resource ('workspace-wide custom property definition'), enumerates the allowed types (text, number, checkbox, or date), and states the return value (propertyId). This distinguishes it from sibling tools like delete_custom_property or set_doc_property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'workspace-wide custom property definition' provides clear context that this tool is for creating global property definitions, not doc-level properties (which siblings handle). However, it does not explicitly state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description's mention of 'insert it into an AFFiNE document' reinforces the mutating nature without adding significant new behavioral details. There is no mention of permissions, reversibility, or behavior when workspaceId is omitted, but the annotations lower the burden. The description adds minimal context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and includes the key output format ('ND-JSON') and target ('AFFiNE document'). Every word contributes to understanding the tool's purpose, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and complete parameter descriptions in the schema, the description covers the essential purpose. It could mention whether a new document is created or an existing one is used, but the presence of the output schema and annotations compensates. The description is adequate 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.
Parameters3/5
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. The description mentions 'structured ND-JSON' which gives context on the expected output format, but it does not add detailed parameter semantics beyond what the schema already provides. It adds marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Generate a structured ND-JSON presentation slide deck outline and insert it into an AFFiNE document.' It specifies a unique verb (generate/insert), a distinct resource (presentation slide deck outline), and the target system (AFFiNE document), distinguishing it from sibling tools like create_doc or create_semantic_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for creating presentation slide outlines, which provides clear context. However, it does not explicitly name alternative tools or specify when not to use it, so it lacks explicit exclusions. The context is sufficiently clear to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds the workspace-level scoping and the fact that no document attachment occurs, which is useful but not extensive. It does not contradict annotations and provides modest additional context beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose and a clarifying contrast. Every sentence earns its place with no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with full schema descriptions and an output schema, the description covers purpose, scope, and the key distinction from related tools. The only minor gap is lack of explicit duplicate-handling behavior, but this is not essential given the annotation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for both 'tag' and 'workspaceId'. The description's phrase 'workspace-level tag entry' reinforces the tag parameter's role but adds minimal new semantic detail beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create') and a clear resource ('a workspace-level tag entry'), and immediately distinguishes itself from the sibling tool add_tag_to_doc. It explains what the operation does not do, removing ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to add_tag_to_doc when attaching a tag to a document, providing a clear alternative and a when-not-to-use case. It does not explicitly state all positive use cases, but 'for future reuse' and the schema's workspaceId hint convey the intended context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds that it creates a root folder and optional children and wraps create_folder, but it does not disclose any additional behavioral traits such as side effects, permissions, or output details. This is minimal added value, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the primary action and a clear wrapper note. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage, output schema, and annotations, the description is adequate. It could further clarify what 'blueprint' means in the AFFiNE context or provide a brief example, but overall it is sufficiently complete for an agent to understand the tool's function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already having a clear description (e.g., workspaceId omission rule, rootFolderName, childFolderNames array constraints). The description only restates the root and child folder concepts without adding deeper parameter semantics, aligning with the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates an AFFiNE organize folder blueprint with one root folder and optional child folders, using a specific verb and resource. It also distinguishes itself from create_folder by explicitly labeling it as a convenience wrapper, making its purpose distinct among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names create_folder as the underlying alternative and positions this tool as a convenience wrapper, implying use for simple folder hierarchy setups. However, it does not explicitly state when not to use it or compare it with other folder-related tools, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, so the description adds value by disclosing that normal deletion is recoverable and permanent deletion bypasses that. This is useful behavioral context beyond the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose. It is concise with no filler, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema, annotations), the description is complete enough. It covers the primary action and the permanent-deletion nuance. The output schema and annotations cover return values and safety profile, so no additional explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all parameters. The description adds a note about when to use permanent deletion, which relates to the permanently and confirmKey parameters, but does not explain them further. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a blob from AFFiNE workspace storage' with a specific verb and resource. It distinguishes from sibling tools like upload_blob and cleanup_blobs by targeting a single blob deletion. The permanent flag nuance adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for deleting a blob and conditional guidance for the permanent flag ('Set permanently only when the blob should bypass recoverable deletion'), but does not explicitly mention alternatives or when not to use this tool. It provides some usage direction, though no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, and the description adds valuable context by specifying the destructive effect is limited to the sidebar link, not the target resource. It also flags the tool as experimental. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose and scope. The 'Experimental:' warning is concise and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and the presence of an output schema, the description provides adequate context about what is deleted and the level of impact. It doesn't explain return values, but the output schema covers that. It is sufficiently complete for a focused link-removal tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (nodeId, workspaceId) already documented with types and descriptions. The tool description adds no additional parameter-level meaning beyond what the schema provides, fitting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('delete') and resource ('AFFiNE organize doc, tag, or collection link node'), and further clarifies the scope ('removes only the sidebar link, not the target resource'). This distinguishes it from sibling tools like delete_folder or delete_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to remove a sidebar link) and clarifies it does not delete the target, but does not explicitly state when to use this vs alternatives or provide exclusions. 'Experimental' hints at caution but is not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description doesn't need to restate that. It adds value by explaining the cascading deletion behavior for connectors, which is not covered by annotations. However, it doesn't mention other potential side effects (e.g., dangling references, permission requirements) that would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, and no fluff. Every word contributes meaning, making it efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and the presence of annotations and an output schema, the description covers the core behavior and the key option. It doesn't elaborate on error cases or prerequisites, but those are partially covered by the schema and annotations. Overall, adequate for a delete tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds marginal detail for pruneConnectors by specifying 'source or target referenced', but this is largely redundant with the schema description. Other parameters have sufficient schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a surface element by id') with a specific verb and resource. It distinguishes from sibling delete tools by targeting 'surface elements' and specifying the cascading behavior for connectors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance for the pruneConnectors option ('Set pruneConnectors=true to also delete any connectors...'), but does not explicitly mention when to use this tool versus alternatives like delete_doc or delete_block. Usage context is implied rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing a safe, non-destructive operation. The description adds valuable context by explaining what the fidelity report contains (markdown loss risk and unsupported AFFiNE-native content), going beyond the basic annotation signals and helping the agent understand the report's behavioral focus.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action ('Export') and concisely conveys both the primary output (markdown) and the additional report. No words are wasted, and it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema covers return value details, so the description only needs to clarify the tool's purpose and report components. It does so effectively by naming 'markdown loss risk' and 'unsupported AFFiNE-native content.' The only minor gap is that it doesn't explicitly relate to export_doc_markdown or analyze_doc_fidelity, but the context is largely complete for a read-only combined export/report tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (docId and workspaceId have descriptions, includeFrontmatter does not). The tool description does not add any parameter-level meaning beyond the schema, leaving includeFrontmatter unexplained. Since coverage is moderate and the parameter names are somewhat self-explanatory, the description neither significantly helps nor hurts, so a baseline-adjacent score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Export') and clearly states the dual output: document markdown and a structured fidelity report highlighting loss risk and unsupported AFFiNE-native content. This distinguishes it from sibling export_doc_markdown (just markdown) and analyze_doc_fidelity (presumably just analysis), making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to choose this tool versus export_doc_markdown or analyze_doc_fidelity. However, the combination of 'markdown' and 'fidelity report' implies that this tool is suitable when both outputs are needed, providing moderate implied guidance without explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that data comes from the 'backend catalog' and lists content types, which is mildly useful context. However, it does not disclose any other behavioral details such as whether the returned data is cached, how the 'vars' parameter affects rendering, or pagination behavior. With annotations, this is adequate but not rich, so a 3 is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the primary action ('Retrieve') and names the resource. It is concise, with no wasted words, and every phrase earns its place by clarifying the scope (official, from backend catalog) and content types (prompt specs, system prompts, visual style guide, rendered templates).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is straightforward, with strong annotations, a complete input schema, and an output schema present. The description clearly states what the tool retrieves, and the output schema covers return-value details. There is a minor ambiguity about whether all listed content types are returned together or separately, but given the schema and annotations, the description is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters: 'promptId' is described with example values, and 'vars' is described as an optional template variable object. The description does not add any parameter-level semantics beyond what the schema already offers. Since schema coverage is high, the baseline of 3 is appropriate; the description neither compensates nor hurts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to retrieve official AFFiNE LLM prompt specs, system prompts, visual style guide, and rendered templates from the backend catalog. It uses a specific verb ('retrieve') and names the resource ('backend catalog') and content types, effectively distinguishing it from any sibling tools, none of which focus on prompt retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: whenever the agent needs official prompt-related content from the backend catalog. It doesn't explicitly mention alternatives or exclusions, but no sibling tool directly competes with this function, making the implied use case sufficient. A score of 4 is appropriate for clear context without explicit 'when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, non-destructive, idempotent behavior. The description adds useful context beyond annotations: 'best-effort profile metadata' indicates that metadata retrieval may be incomplete or opportunistic, and 'direct URL' mentions an output component. These are behavioral traits not covered by annotations, and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action, and includes only high-value additions ('best-effort profile metadata', 'direct URL'). Every word earns its place with no filler or restatement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id operation with a single required parameter, full schema coverage, rich annotations, and an output schema, the description is adequate and complete. It does not over-explain return values (output schema covers that) but includes behavioral nuances. Minor gaps around error cases or explicit usage alternatives are not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the single parameter 'id' described as 'Workspace ID'. The description does not add additional meaning about the parameter's format, constraints, or usage beyond what the schema already 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and identifies the resource 'workspace details', adding 'with best-effort profile metadata and a direct URL' to clarify what data is returned. It clearly distinguishes from siblings like list_workspaces (list all workspaces) and create/update/delete mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single workspace by ID via the required 'id' parameter, but it does not explicitly state when to use this tool versus alternatives like list_workspaces, nor does it provide any exclusions or alternative tool names. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's read-only statement adds little. However, it adds useful context beyond annotations by noting that results include title metadata and an inTrash flag, which helps the agent understand the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the primary purpose, and includes relevant result details without any filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only nature, rich annotations, and the presence of an output schema, the description adequately covers core selection needs. It mentions the inTrash flag, which adds value. The lack of alternative-tool guidance is a minor gap but is more relevant to the usage-guidelines dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is fully described with 100% coverage for all three parameters, so the description need not repeat them. It adds no extra semantic detail beyond what the schema already documents, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' with a specific resource 'documents' and the filtering criterion 'tag'. This distinguishes it from sibling tools like list_docs (all documents) and find_doc_by_title (by title).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for tag-based filtering but does not explicitly mention when to use this tool over alternatives like search_docs or list_docs. It provides no exclusions or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the annotations: it warns to inspect the applied/status field and explains that a false server result is reported as not_applied, not success. This reveals potential partial failure and the response format. Annotations already signal a write operation (readOnlyHint=false), but this additional nuance is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, followed by a concise caveat about response handling. No redundancy or filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless mutation with an output schema, the description adequately covers the purpose, scope, and key response nuance. It lacks usage context or alternatives, which is partially captured in Usage Guidelines, but is otherwise complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty). Descriptions cannot add parameter meaning where none exist. Baseline for 0 params is 4, and the description correctly focuses on the operation and response rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: mark every current-user notification as read. It specifies the verb (mark), the resource (notifications), and the scope (current-user), distinguishing it from sibling tools like list_notifications which read notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives. It does not mention that list_notifications is for viewing notifications, nor does it address when marking all as read is appropriate. The reader must infer the use case from the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly=False, so the description's 'set' aligns with a mutation. It adds context that content remains unchanged, which is useful. However, it doesn't disclose other potential side effects (e.g., notifications, idempotency), though annotations already cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences, each earning its place. The description is front-loaded with the core action and immediately clarifies what it doesn't do.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with two parameters and an output schema present. The description covers the purpose, non-destructive behavior, and an alternative tool, making it complete enough for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already describes id and resolved clearly. The description doesn't add parameter-level detail beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Set a comment thread's resolved state without changing its content.' This uses a specific verb and resource, and explicitly distinguishes from delete_comment by saying 'Use delete_comment only when the comment should be removed.' This differentiates it from sibling tools like delete_comment and update_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance by naming delete_comment as the alternative for removal, and implies this tool is for toggling resolution without content changes. It doesn't mention update_comment directly, but the 'without changing its content' phrasing covers the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=false. Description adds that the operation rebuilds the allow-list from current workspace documents and can change which docs appear, giving useful context that membership will be recalculated. Could be more explicit about handling of manually-added docs but is satisfactory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, starts with action verb, no filler. 'This can change which docs appear' is informative but concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With detailed schema and output schema, description covers the core behavior and caveat. It does not address interaction with manually-added docs or suggest when to prefer this over manual management, but overall adequate for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has full descriptions for all parameters including nested rules structure, match/filter operators. Description adds no further parameter meanings 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Replace' plus resource 'AFFiNE collection's rules' and outcome 'rebuild its allow-list from current workspace documents'. This clearly distinguishes it from sibling tools like add_doc_to_collection and update_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or exclusions. It implies usage when wanting to change collection membership by replacing filter rules, but does not contrast with alternatives like manual doc add/remove. Thus only implied usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a non-read-only, non-destructive, open-world operation. The description adds the 'Experimental' stability warning and explicitly states that null removes the icon, which is a reversible clearing behavior. It also scopes the effect to the 'sidebar icon,' which is contextual beyond annotations, though no side effects or auth requirements are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each adding distinct value: purpose, parameter options, and an experimental caveat. It is front-loaded and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, one with polymorphic types), the output schema, and annotations, the description is largely sufficient. It covers the core behavior and parameter forms. The main gap is the undocumented workspaceId and lack of explicit sibling differentiation, but these are minor given the structured data provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (folderId and icon have descriptions, workspaceId does not). The description's 'Pass an emoji string, a full icon object, or null to remove it' summarizes the icon parameter but is largely redundant with the schema's detailed icon description. It provides no additional meaning for folderId or workspaceId, so it adds limited value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set or clear the sidebar icon on an organize folder,' specifying the action (set/clear) and resource (sidebar icon on organize folder). This distinguishes it from sibling tools like update_doc_icon by explicitly scoping to 'organize folder' and 'sidebar icon.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for folder icon updates but does not explicitly mention alternatives or when-not-to-use scenarios. The scope is clear, but there is no direct comparison to get_folder_icon or update_doc_icon, and the 'Experimental' tag only hints at caution without clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent write operation. The description adds valuable behavioral context by explaining the immediate side effects of parentDocId (linked into sidebar tree) and folderId (placed inside folder), which goes beyond annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the main action, and avoids fluff. Every sentence contributes meaningful information about the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (so return values aren't needed in the description) and the parameter schema covers all 5 parameters, the description sufficiently explains the core purpose and key side effects. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds minimal extra meaning—mostly restating that parentDocId links the doc and folderId places it in a folder. This is helpful but not transformative, aligning with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new AFFiNE document') and specifies the resource and side effects (linking into sidebar tree, placing in folder). This distinguishes it from sibling tools like create_doc_from_markdown or create_semantic_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (creating a new document with optional content and sidebar placement) but does not explicitly mention alternatives or exclusions. No guidance is given on choosing this over sibling tools like create_doc_from_markdown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds the null-return behavior when no icon is set, and clarifies it's a read operation. This is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that says exactly what the tool does and the key edge case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple read operation, a rich output schema, and strong annotations, the description covers the essential behavior. The only missing piece is clarity around the optional workspaceId parameter, which slightly reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: docId is well described, but workspaceId has no description in the schema. The description does not compensate by explaining workspaceId or its role, leaving a significant gap for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('current sidebar icon of a document'), clearly distinguishing it from write tools like update_doc_icon and from folder icon tools. It also conveys the scope (sidebar icon) precisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context for when to use this tool is clear: whenever the current sidebar icon of a document is needed. It does not explicitly state exclusions or alternatives, which is why it is not a 5, but the read vs update contrast with sibling tools is implicitly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read operation. The description adds no additional behavioral context beyond the purpose itself, with no mention of filters, return format, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource. No wasted words, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read operation with a rich schema (100% coverage), comprehensive annotations, and an output schema present. The description, while brief, is complete enough given the structured fields already convey filtering details and expected outputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly documented (e.g., rowBlockIds 'Optional row block ID filter. Omit to return all rows.'). The description adds no extra parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads row titles and cell values from an AFFiNE database block, using the specific verb 'Read' and identifying the resource. It distinguishes from sibling tools like read_database_columns by explicitly mentioning cell values and row titles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies clear usage: it is for reading database cell values. It does not explicitly name alternatives or exclusions, but the distinction between this tool and read_database_columns is contextually evident. Lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses non-obvious behaviors: title column text is stored on the row paragraph block, and select columns auto-create options by label. These details complement the annotations (readOnlyHint=false, openWorldHint=true) and add transparency about side effects without contradicting any hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no wasted words. The first sentence states the core action, and the subsequent sentences add high-value details about cell mapping and edge cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested objects and 5 parameters, the description covers key usage aspects: how to map cells, special handling of the title column, and select column behavior. An output schema exists, so return values need not be described. A slight gap is the lack of elaboration on linkedDocId, but the schema already explains that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 5 parameters with descriptions, so baseline is 3. The description enriches the cells parameter by explaining that values map by column name/ID and that select column labels auto-create options, which adds meaning beyond the schema's generic definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Add a row to an AFFiNE database block', which is a specific verb and resource. It clearly distinguishes from sibling tools like update_database_row and delete_database_row by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear how-to context but does not explicitly state when to use this tool versus alternatives such as update_database_row or read_database_cells. Usage is implied by the word 'Add' and the tool's name, but no alternative tools or exclusionary conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds the constraint that the document must already exist, but does not disclose behavior like duplicate handling, error conditions, or side effects. Adequate but not rich given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, action first, no redundant words. The first sentence states the purpose, the second gives usage guidance. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with rich schema descriptions, annotations, and an output schema present. The description provides enough context for selection and invocation, though it could mention duplicate behavior. Overall it is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all three parameters with descriptions (100% coverage), including context for workspaceId and collectionId. The description does not add any additional parameter semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Add an existing document id to an AFFiNE collection allow-list.' It clearly distinguishes from sibling tools like update_collection_rules (rule-driven) and remove_doc_from_collection (removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states an alternative: 'Use update_collection_rules instead when membership should be rule-driven.' This gives clear when-not-to-use guidance and names the alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'destructive cleanup' and 'permanently release.' It adds a safety caution about confirming necessity, which goes beyond the annotation flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and each sentence provides essential information: what it does and when to use it. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with rich annotations and an output schema, the description covers the action, scope, and safety condition. It is complete enough for an agent to understand when and how to invoke it, though it relies on the schema for parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both workspaceId and confirmWorkspaceId fully described in the schema. The tool description adds no additional parameter-specific context, but the schema already provides sufficient meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('permanently release') and resource ('blobs that were already marked deleted'), clearly differentiating it from `delete_blob` and other workspace tools. It precisely states both the action and the precondition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit condition for use ('should be used only after confirming deleted blobs are no longer needed') and categorizes the tool as destructive cleanup. It does not explicitly name alternatives, but the phrasing implies a follow-up to deletion, which gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool 'writes workspace sidebar metadata,' providing behavioral context beyond the annotations (e.g., that it is a lightweight metadata write rather than a document operation). This aligns with readOnlyHint=false and idempotentHint=false without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and immediately adds a clarifying constraint. Every word earns its place with no redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich schema (3 params, nested rules object) and output schema present, the description need not explain return values. It provides essential context about the tool's side effect (writing sidebar metadata) and its boundary (not creating documents), making it sufficient for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all parameters (name, rules, workspaceId). The description only mentions 'optional rules,' which adds no new semantic detail beyond what the schema already provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new AFFiNE sidebar collection with optional rules' with a specific verb and resource. It also explicitly distinguishes what it does not do ('does not create documents'), setting it apart from document creation tools and clarifying its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates when to use the tool (creating a new collection) and provides an exclusion by noting it does not create documents. However, it does not explicitly mention alternatives like update_collection or list_collections for other collection operations, so usage guidance is clear but not fully comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the description does not need to restate the safety profile. It adds value by noting 'writes collaboration state,' clarifying the nature of the write operation and its scope, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states the action and target; the second adds a necessary sibling distinction. There is no redundant text, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and key alternative, while the schema, annotations, and output schema supply parameter and return details. It does not mention prerequisites like document existence, but 'existing document' implies it. For a creation tool with this schema richness, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 thoroughly. The description does not add parameter-specific details beyond the schema, but it implicitly reinforces that content is for a new comment. This meets the baseline for high schema coverage without further elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new comment on an existing document, using a specific verb and resource. It also explicitly distinguishes itself from update_comment, which is the primary sibling tool for editing comments, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this for creating new comments, and explicitly names update_comment as the alternative for editing existing comments. It does not provide broader when-not-to-use guidance for other comment-related tools like delete or list, but the key distinction is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by labeling the tool 'Experimental' and clarifying that it only changes sidebar organization, not document content. This goes beyond the structured annotations and helps manage expectations about side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the key purpose, and every word adds value. It is concise without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, has full parameter schema coverage, and an output schema exists (per context signals). The description covers the essential purpose and scope, but could mention duplicate-name behavior or error cases. Still, it is adequately complete for an experienced agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 four parameters. The description does not add parameter-specific meaning beyond what is in the schema, so it meets the baseline but does not elevate it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'create an AFFiNE organize folder node in the sidebar tree.' It uses a specific verb and resource, and distinguishes from sibling tools by clarifying it only affects sidebar organization, not document content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by defining its scope ('create an AFFiNE organize folder node') and explicitly states what it does NOT do ('not document content'), which acts as an exclusion. However, it does not name alternative tools for document creation or other operations, so it lacks explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context specifically that referenced documents are preserved, reducing surprise about side effects. It does not elaborate on irreversibility or permissions, but 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the key verb front-loaded. The first sentence states the primary action, and the second clarifies a crucial nuance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple destructiveness of the operation, the description covers the essential behavioral distinction (documents not deleted). The output schema and annotations fill in remaining context. It is slightly thin on post-deletion effects, but adequate for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters already have clear descriptions (workspaceId and collectionId). The description adds no new parameter-level meaning, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') on a specific resource ('AFFiNE sidebar collection') and explicitly distinguishes its scope by clarifying that it removes only metadata, not referenced documents. This differentiates it from sibling tools like delete_doc and delete_workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context about what the tool does and its non-effect on documents, which helps the agent decide when to use it (e.g., when only the collection should be removed, not the docs). It does not explicitly name alternatives but the scope clarification is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds crucial nuance: it is a soft-delete, and existing values are hidden. This goes beyond the annotation by explaining the actual effect (hiding, not permanent destruction), which is valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and key qualifiers. Every word earns its place; no fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with an output schema, the description adequately covers the action, the target resource, the identifier flexibility, and the soft-delete behavior. It could have added note about reversibility or effects on existing docs, but that may not be necessary given the output schema and simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a description for 'property' ('Property id or name') but not for 'workspaceId'. The description reinforces that the property can be identified by id or name, which adds slight value. However, with 50% schema coverage, the description could have compensated more by explaining workspaceId semantics or the relationship between the parameters, but it doesn't.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('soft-delete') and resource ('workspace custom property definition'), and clarifies the lookup mechanism ('by propertyId or name'). This clearly differentiates from sibling tools like delete_tag or delete_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not name alternative tools, but it provides enough context: it targets custom property definitions and specifies how to identify them. Since the operation is a soft-delete, it implies this is used when you want to remove a property while preserving underlying values. No exclusions or explicit alternatives, but clear enough for a single-purpose tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the specific behavioral detail that returns null when no icon is set, which is not covered by the readOnlyHint annotation. It also flags the tool as 'Experimental,' providing a caveat. The annotations already declare the safety profile, so this additional context is valuable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded: 'Read' immediately conveys the action, followed by the resource and key return behavior. Three sentences with zero fluff, each earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with a clear annotation profile, output schema, and minimal parameters, the description covers the essential behavior (including null return and experimental status). It lacks an explicit mention of workspaceId, but the overall picture is sufficient for a safe getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a description for folderId but not for workspaceId (50% coverage). The description does not explain workspaceId or add syntax details, though it does reinforce that folderId refers to an organize folder's icon. This is adequate but not compensatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action ('Read the current sidebar icon') and the resource ('an organize folder'), clearly distinguishing it from sibling tools like update_folder_icon (write) and get_doc_icon (documents). It also specifies the null return case, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is a read-only operation for folder icons, implying it should be used instead of update_folder_icon when only reading is needed. However, it does not explicitly name alternatives or describe when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds specific inspection scope (native structure, tags, fallback risk) and the timing context, providing meaningful behavioral context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb and object, with no redundant words. Every word contributes to understanding: 'native structure, tags, and fallback risk before instantiation.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description sufficiently covers purpose, usage context, and inspection scope. It might benefit from mentioning the relationship to instantiate_template_native or analyze_doc_fidelity, but it is complete enough for a read-only inspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already well-described in the schema. The description does not add extra parameter semantics beyond implying templateDocId via 'template doc.' Baseline 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Inspect' with a clear object: 'a template doc's native structure, tags, and fallback risk before instantiation.' This clearly distinguishes it from siblings like instantiate_template_native and analyze_doc_fidelity by emphasizing pre-instantiation inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before instantiation' provides a clear context for when to use this tool, but it does not explicitly name alternatives or exclusion criteria. The timing cue is useful, though it could be more explicit about not using get_doc/read_doc for this purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent mutation (readOnlyHint=false, destructiveHint=false). The description adds valuable behavioral context beyond that: it explains the native-clone-first strategy and conditional fallback to markdown, which is non-obvious and not inferable from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core action and includes the key fallback condition. Every word earns its place; there is no filler or redundant repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, an output schema, and annotations, the description is fairly complete. It explains the core execution strategy and fallback behavior, which is the most important detail. It does not mention specifics like workspaceId handling or tag preservation, but the schema already covers those, and the output schema exists, so the description need not explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all seven parameters well-described (e.g., allowFallback, preserveTags, variables). The description's mention of 'native AFFiNE block cloning' and 'markdown materialization' adds slight context to the allowFallback parameter, but overall it contributes little beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Instantiate a template using native AFFiNE block cloning when supported, falling back to markdown materialization only when necessary.' It identifies the specific verb (instantiate), the resource (template), and the tool's unique native-clone-first behavior, which distinguishes it from sibling tools like create_doc_from_markdown or append_markdown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use native block cloning when supported, and fallback to markdown only when necessary. It implies this is the preferred tool for template instantiation, but it does not explicitly name alternatives or state when NOT to use this tool (e.g., when you want a pure markdown doc). Slight gap for full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that removing is non-destructive and doesn't alter rules, which is useful context beyond the annotations. It doesn't describe error behavior for non-members, but that's a minor gap given the simple scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with no filler. It immediately states the action and its non-effects, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-document removal with annotations, full schema coverage, and an output schema, the description covers the operation and its boundaries. It lacks explicit mention of return values or error cases, but the output schema likely covers that. Overall, it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the schema, covering 100% of them. The description does not add additional meaning beyond what the schema provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a document id from an AFFiNE collection allow-list' – a specific verb+resource+object. It explicitly distinguishes itself from deleting the document or changing collection rules, differentiating it from siblings like delete_doc, update_collection_rules, and add_doc_to_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the operation's scope and exclusions ('does not delete the document or change collection rules'), which signals when to use this instead of destructive or rule-modifying tools. However, it doesn't explicitly name alternatives like add_doc_to_collection, so some inference is needed for the when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false). The description adds the specific behavioral trait of setting session cookies, which explains the mechanism and prerequisite nature beyond the annotation. It does not cover edge cases like session expiry or invalidation, but the core behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with two concise clauses, front-loading the main action and quickly stating the side effect. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter authentication tool with an output schema, the description provides the essential purpose and side effect. It lacks explicit mention of session duration or behavior on repeated sign-in, but given the low complexity and output schema presence, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters (email and password) with descriptions. The tool description adds no additional parameter semantics, but the baseline of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Sign in to AFFiNE'), the method ('using email and password'), and the resource (AFFiNE). It also mentions the side effect of setting session cookies, which distinguishes it from all sibling tools that operate on workspaces and docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a prerequisite for subsequent calls by stating it 'sets session cookies for subsequent calls,' providing clear context. There are no alternative sign-in tools among siblings, so no explicit when-not-to-use guidance is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey mutation (readOnlyHint=false, idempotentHint=false). The description adds useful behavioral context: the icon slot is the 'sidebar icon' and that null removes it, which explains the mutation scope beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary purpose, then a succinct explanation of accepted inputs. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and a simple parameter set, the description covers the core behavior and removal semantics. It omits any mention of the optional workspaceId parameter, but this is minor given the tool's simplicity and the presence of schema info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% and the description repeats what the schema already explains (emoji string, object, or null). It doesn't add meaning for the undocumented workspaceId parameter, so it only partially compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Set or clear the sidebar icon (the Notion-style emoji slot) on a document.' This is a specific verb+resource combination that distinguishes it from siblings like update_doc_title and update_folder_icon.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for the tool's scope ('on a document') and the ability to clear with null, which implies when to use. However, it doesn't explicitly mention alternatives or exclusions, like contrasting with update_folder_icon, so it misses a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-readonly, non-destructive write operation. The description adds value by revealing that the rename updates both workspace metadata and the internal page block title, which is not derivable from annotations alone. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that leads with the core action and then adds specific detail. Every word contributes value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple rename tool with annotations and an output schema present, the description adequately explains the tool's effect. It lacks edge-case or prerequisite details, but these are not necessary for such a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes docId and title, but the description clarifies that the title parameter affects both the sidebar and internal page block, adding meaning beyond the schema's 'New title'. With 67% schema coverage, the description partially compensates, though workspaceId remains unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Rename a document' with a specific verb and resource, and further clarifies the scope by mentioning both the sidebar title and internal page block title. This distinguishes it from sibling tools like update_doc_icon or move_doc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for renaming documents but does not explicitly state when to use it versus alternatives or provide exclusions. It gives context about what is updated but no direct guidance on when this tool is preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive mutation. The description adds valuable behavioral context: it returns a blob key and does not attach the blob to a document. This clarifies the tool's side effects without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences long and front-loaded with the core action and outcome. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the extensive schema coverage, the description provides sufficient context: what the tool does, what it returns, and its key limitation (not attaching to a document). It could mention constraints like size limits, but these are likely outside the tool's core behavior, and the output schema is present to clarify return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all five parameters with precise meanings and defaults. The description does not add any parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Upload a file or blob into AFFiNE workspace storage and return its blob key.' It uses specific verbs and resources, and explicitly distinguishes it from siblings by noting it 'does not attach it to a document by itself.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (for storing content in workspace storage) and gives a boundary condition ('does not attach it to a document by itself'), suggesting other tools are needed for attachment. It doesn't name explicit alternatives, but the context is clear enough for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation nature is known. The description goes beyond annotations by disclosing that non-applicable style fields are reported in the 'ignored' list, and by explaining connector behaviors (arrows between shapes or points). This adds valuable behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences, each earning its place: purpose, shape variants, connector behavior, usage context, and the 'ignored' field behavior. It is front-loaded with the action and resource, and contains no fluff or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large schema (30 parameters) with detailed descriptions and an output schema present, the description provides sufficient high-level context: supported element types, connector modes, and response behavior for ignored fields. Full information is available for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with rich per-parameter details (e.g., fillColor palette family, targetPosition relative/absolute semantics). The description does not add significant parameter-level meaning beyond summarizing element types. Baseline of 3 is appropriate because the schema carries the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the action verb 'Add' and clearly specifies the resource: 'shape, connector, text, or group to the AFFiNE edgeless canvas surface.' It also names the specific shape types and connector modes, and the phrase 'Use for building diagrams programmatically' reinforces the tool's scope. This clearly distinguishes it from sibling tools like update_surface_element and delete_surface_element.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context: 'Use for building diagrams programmatically.' It does not explicitly state when not to use this tool (e.g., for modifying existing elements, use update_surface_element), but the sibling relationships and the 'mirrors update_surface_element' note implicitly guide the agent. This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds the auth-dependent nature ('currently authenticated') but no other behavioral traits, matching the baseline for well-annotated tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, action first, no filler or redundant detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema present, the description provides sufficient context for a simple read-only verification tool, including its use case and the resource returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is trivially 100%. The baseline of 4 applies because no parameter explanation is needed; the description adds no param info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Return' and specifies the resource as 'the currently authenticated AFFiNE user profile', clearly distinguishing it from siblings like sign_in or update_profile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool ('to verify credentials before workspace or document operations'), providing clear context, though it does not name alternatives or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond annotations: the cascading removal from documents and the rejection of ambiguous names with candidate ids. Annotations already indicate destructive behavior, but these specifics help the agent understand side effects and error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, scope, and key edge case without any waste. It is efficiently structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the annotations, the description sufficiently covers the main behavior, scope, and important error handling. The disambiguation behavior is explicitly stated, making the tool safe to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters with detailed descriptions, including that 'tag' accepts an id or name and that ambiguous names are rejected. The description reinforces these points but does not add new parameter-specific information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: deleting a workspace-level tag and removing it from every referenced document. This distinguishes it from related tools like remove_tag_from_doc by specifying workspace-level scope and cascading effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool by emphasizing workspace-level tags and the removal from all documents. It does not explicitly name alternatives or exclusions, but the scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, it discloses the stable envelope, preservation of edge cursor/pageInfo/serverTotalCount, and clarifies that unreadOnly is a client-side filter not affecting server counts. This is significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently convey the core purpose and key behavioral nuances without redundancy. Front-loaded with 'List one server page' provides immediate clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, paginated list tool with an output schema, the description is complete: it covers pagination envelope, cursor behavior, and the client-side filter semantics. No critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully documented. The description reinforces unreadOnly behavior but adds no new parameter-level meanings beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists one server page of current-user AFFiNE notifications, with specific resource and scope. It distinguishes from sibling tools like read_all_notifications by emphasizing pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on pagination and client-side filtering, but does not explicitly name alternatives or state when not to use. It implies usage for paginated notification retrieval but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful context beyond these: it is flagged 'Experimental', and it specifies the data source ('from the folders workspace DB'), which helps set expectations about scope and reliability. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the essential action and scope. Every sentence earns its place: the first defines what the tool does and its experimental nature, the second gives direct usage guidance. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with one optional parameter, annotations covering safety, and an output schema describing return values, the description is complete. It specifies the resource, the context (sidebar organize nodes), and the recommended use case, leaving no significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter (workspaceId) has a complete schema description that explains when to omit it (when AFFINE_WORKSPACE_ID is configured). The tool description adds no additional parameter-specific details, so with 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool with a specific verb ('list') and resource ('AFFiNE sidebar organize folder and link nodes'), sourced from 'the folders workspace DB'. It distinguishes itself from sibling list tools like list_workspace_tree or list_docs by targeting a specific node type, and the 'Experimental' label adds context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this before moving or deleting organize nodes.' This provides clear context and ties to related sibling operations (move_organize_node, delete_organize_link). It does not explicitly name alternatives or exclusions, but the guidance is direct and sufficient for the tool's simple read-only purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by disclosing that results include raw xywh strings plus parsed {x,y,width,height} bounds, and that Y.Text fields are serialized to plain strings. This exceeds mere annotation repetition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, well-structured and front-loaded. The first sentence states the main purpose and scope; the second adds return format details and filter options. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to detail every return field, but it still mentions the key return shape (xywh strings + parsed bounds) and Y.Text serialization. The tool is a list operation with optional filters, and the description covers the essential context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the schema. The description lightly reinforces the 'type' and 'elementId' filters but does not add meaningful semantics beyond what schema descriptions already provide. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'shape/connector/text/group elements on the AFFiNE edgeless canvas surface', which differentiates it from sibling tools like add/update/delete_surface_element. It also mentions optional filters, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you need to list surface elements with optional type or id filters. It does not explicitly name alternatives or exclusion criteria, but the sibling names like get_edgeless_canvas imply a distinction, and the description is sufficient for basic usage decisions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful context: the scope is workspace-level tags, and it returns the number of attached documents, which goes beyond the safety profile conveyed by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the core function, the second gives a targeted usage directive. No filler, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and strong annotations, the description covers purpose, scope, and usage guidance sufficiently. The schema handles the parameter semantics, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (workspaceId) with 100% coverage. The description adds no extra parameter-level detail beyond the schema, but the 'workspace-level' phrasing slightly reinforces the workspace scope. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all workspace-level tags and their document counts, a specific verb+resource+scope. This distinguishes it from sibling tools like list_docs_by_tag, which lists documents by tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before tag mutation when the exact tag name or id is unknown. This provides a clear usage context and implies when not to use it (when tag info is known), though it doesn't name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds useful behavioral nuance with 'best-effort profile metadata' (acknowledging possible incompleteness) and 'direct URLs' (indicating response content), which goes beyond the schema and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence with no filler. It front-loads the core purpose and quickly adds distinguishing details, making every word earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, read-only listing tool with one optional parameter, rich annotations, and an output schema. The description covers the essential behavior ('list available workspaces', profile metadata, direct URLs) and nothing more is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the only parameter (includeProfile) with a clear description. The tool description does not add parameter details, but none are needed since the schema fully explains the parameter's meaning and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('available AFFiNE workspaces'), and adds distinguishing details ('best-effort profile metadata and direct URLs') that set it apart from related tools like list_workspace_tree. It clearly states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for enumerating available workspaces, which is distinguishable from sibling operations like get_workspace, create_workspace, update_workspace, and delete_workspace. However, it does not explicitly name alternatives or state exclusions, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it explains the order of operations (destination added before source removed), cycle rejection, and explicit reporting of partial outcomes. This is critical for an agent to anticipate side effects and understand the tool's safety profile, especially given that destructiveHint is false but a source link may be removed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and packs in essential behavioral details without redundancy. Every clause earns its place, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (potential partial outcomes, cycles, and order sensitivity), the description comprehensively covers the key edge cases and execution guarantee. The presence of an output schema means the description need not detail return values, and the behavioral notes sufficiently prepare an agent for expected side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents three of four parameters. The description adds meaning by clarifying the order involving toParentDocId and fromParentDocId, and by alluding to cycle rejection which constrains valid values. However, workspaceId remains undocumented in both schema and description, and the description does not provide additional syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('move') and the resource ('a doc in the AFFiNE sidebar'), which precisely identifies the tool's function. This differentiates it from sibling tools like move_organize_node that operate on different entity types, and from delete_doc or create_doc which have distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its statement of moving docs in the sidebar, but it does not explicitly compare to alternatives or state when-not-to-use. For instance, it does not contrast with move_organize_node or mention scenarios where adding a link without moving might be preferred. The behavioral details suggest expectations but do not provide explicit selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutation (readOnlyHint=false) and non-destructive intent. The description adds 'Experimental' status and explicitly states it 'preserves the target document, tag, or collection' and 'changes only sidebar placement', providing useful side-effect context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the experimental warning, and every phrase adds value without redundancy. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple move operation, the description adequately covers purpose, scope, and effect on the target. With an output schema and annotations present, no major information gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (nodeId, parentId, index, workspaceId) are fully documented in the schema. The description does not add parameter syntax or format details, keeping it at the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('move') and resource ('AFFiNE organize folder or link node'), and clearly distinguishes from sibling tools like move_doc by noting it changes only sidebar placement and preserves the target document, tag, or collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for reorganizing sidebar nodes, not moving content. It doesn't explicitly name alternatives, but the scope statement ('changes only sidebar placement') implicitly differentiates from move_doc and other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the bar is appropriately lower. The description adds value by detailing exactly what is returned (columns, select options, view column mappings) and clarifies it works on empty databases, going beyond the annotation-only safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence front-loads the action and object, while the second sentence adds essential usage context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter schema, rich annotations, and presence of an output schema, the description is complete enough for an agent to select and invoke the tool correctly. It covers both what the tool does and a key scenario where it is particularly useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters (docId, workspaceId, databaseBlockId) already documented in the schema. The description does not add parameter-level nuance, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Read schema metadata for an AFFiNE database block, including columns, select options, and view column mappings.' This is a specific verb+resource and clearly distinguishes the tool from siblings like read_database_cells, which focuses on cell data. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it is 'Useful for empty databases before any rows exist,' which provides clear context for when to prefer this tool. However, it does not explicitly mention alternatives or exclusions, so it stops short of full when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description reveals important behavior: 'Experimental', 'changes sidebar metadata only', and 'does not rename documents inside the folder'. This adds valuable context about scope and limitations, exceeding what readOnlyHint/destructiveHint alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with 'Experimental' and the core action. Every word adds value, and the limitation is stated without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with full schema coverage and an output schema, the description adequately covers the operation's scope and side effects. The 'Experimental' warning and the metadata-only clarification make it sufficiently complete for an agent to decide on usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameter descriptions already explain folderId and name. The description adds no new parameter-specific meaning beyond what the schema provides, so it meets the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'rename an AFFiNE organize folder node'. It clearly distinguishes from sibling tools like create_folder, delete_folder, and move_organize_node by focusing on the rename operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for renaming a folder node, but provides no explicit guidance on when to prefer it over alternatives or when it should not be used. The added caveat about not renaming documents inside is a behavioral note, not a usage directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds meaningful behavioral context by stating that the operation does not change rules or allow-list, which clarifies the scope of the mutation. It does not fully explore open-world side effects, but with annotations covering the safety profile, this additional scope disclosure is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the action ('Rename') and includes a crucial scoping qualifier ('without changing its rules or allow-list'). Every word earns its place; there is zero waste, and the structure is immediately comprehensible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward rename operation, the description is complete. It identifies the exact purpose and the boundary of the operation. Given that an output schema exists and the input schema has full parameter coverage, the description does not need to elaborate return values or parameter details. The presence of sibling tools and annotations rounds out the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all three parameters have clear descriptions in the schema. The tool description itself does not add extra parameter syntax or format details, which is acceptable given the schema does the heavy lifting. The description's mention of 'without changing rules or allow-list' indirectly clarifies that the 'name' parameter is the only changed field, but this is already implied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Rename') and clearly identifies the resource ('existing AFFiNE sidebar collection'). It distinguishes the tool from siblings by explicitly scoping the action to renaming only, and clarifying that rules and allow-list remain unchanged. This unambiguously differentiates it from update_collection_rules and other collection mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need to rename a collection while preserving its rules and allow-list. It hints at the alternative (update_collection_rules) by stating what this tool does NOT do, but does not explicitly name that alternative. This provides clear context without an explicit exclusion or direct sibling comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it flags the tool as 'Experimental' and warns about duplicate link creation for existing nodes. Since annotations already disclose read-only/destructive/idempotent traits, the description's additional context is sufficient. No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the experimental warning and a clear verb. It conveys purpose, caveat, and alternative without unnecessary detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 5 parameters and an output schema, the description provides the essential selection and invocation context: what it does, the alternative, and a caveat. It doesn't explain return values, but the output schema exists. Slightly more detail on duplicate behavior could improve it, but it is complete enough for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all 5 parameters (100% coverage), so the description does not need to explain parameters. It adds minimal extra meaning by mapping the 'type' enum to 'doc, tag, or collection', but this aligns with schema. Baseline 3 is appropriate as the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add) and the resource (a doc, tag, or collection link under an AFFiNE organize folder). It also distinguishes from the sibling tool move_organize_node by explicitly naming it, making the purpose unambiguous and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides an alternative: 'Use move_organize_node for an existing link node instead of creating a duplicate link.' This clearly tells the agent when not to use this tool and what to use instead, exceeding the minimum requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations. Annotations already mark the operation as destructive, but the description specifies that deletion is permanent and that success is only reported when AFFiNE confirms the mutation. This informs the agent about the irreversible nature and the confirmation mechanism, which is not present in the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly conveys the core action and a critical behavioral nuance. Every word contributes meaning, with no fluff or repetition. It is well front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description is sufficiently complete given the rich annotations and output schema. It covers the key aspects: permanence and confirmation behavior. It does not discuss side effects on workspace contents, but that is likely unnecessary for this tool's context. The existence of an output schema also reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'confirmWorkspaceId' fully described in the input schema. The description itself does not directly elaborate on the parameters, but it does provide a high-level hint about the confirmation requirement ('report success only when AFFiNE confirms the mutation'), which aligns with the purpose of 'confirmWorkspaceId.' Since the schema already handles the parameter details, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb and resource: 'Delete a workspace permanently.' It goes beyond simply restating the name by adding the 'permanently' qualifier, which distinguishes it from temporary hide or update operations. This also differentiates it from sibling tools like update_workspace or create_workspace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: this tool is for permanently deleting a workspace. It doesn't explicitly state when NOT to use it or mention alternatives, but the verb 'delete' and the permanent qualifier make the intended use clear. Given the sibling list, an agent could infer that for modifications, update_workspace is appropriate, but the description itself provides no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by stating "This changes sharing state," making it clear this is a state-changing operation rather than a destructive one. The annotations (readOnlyHint=false, idempotentHint=false) indirectly support this, and the description explicitly names the reversible nature of the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose and followed by a concise note on the reversal path. Every sentence adds value; no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description combined with annotations and a full output schema covers the essentials: what it does, that it reverses via revoke_doc, and the state-changing nature. It does not elaborate on permissions or output details, but those are partially covered by the schema and annotations, and the description is sufficient for selection and basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well-documented in the schema. The description does not add additional parameter semantics beyond what the schema provides, which matches the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "Make a document publicly accessible through AFFiNE public sharing." It uses a specific verb (make publicly accessible) and resource (document), and distinguishes itself from the sibling tool revoke_doc by framing it as the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus an alternative: "use revoke_doc to disable public access later." This makes the scope of use clear and points to the complementary tool for the reverse action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive flags, but the description adds valuable context by clarifying that this operation detaches a tag 'without deleting the workspace-level tag.' This clarifies the exact scope of mutation and prevents the agent from assuming the tag itself is deleted. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the primary action, and the second provides the key alternative. It is front-loaded with the core function and contains no redundant or filler content, making it highly scannable for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter operation with an output schema present, the description covers the essential context: what the tool does, its non-destructive nature regarding the tag, and when to use an alternative. It does not elaborate on edge cases or idempotency, but these are not critical given the low complexity and existing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters (tag, docId, workspaceId) with clear meanings, achieving 100% coverage. The description adds no additional detail about parameter semantics beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Detach a tag from one document' with the specific resource being the tag-document relationship. It explicitly distinguishes this from delete_tag by noting 'without deleting the workspace-level tag' and 'Use delete_tag only when the tag should be removed from every document.' This makes the purpose unambiguous and differentiates it from related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it explains when to use this tool (detach from one document) and when to use the alternative delete_tag ('only when the tag should be removed from every document'). This direct comparison helps the agent choose correctly among tag-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and readOnlyHint, so the bar is lower. The description adds that destruction is limited to that comment and contrasts with resolve_comment, giving useful behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the action, second warns about destructiveness and offers an alternative. Every word earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter delete tool with full annotations and output schema, the description is complete. It covers purpose, destructive nature, and alternative, making it fully sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'id' parameter well-documented and referencing source methods. The description adds no extra parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an existing comment by id' with a specific verb and resource. It distinguishes from sibling tools by explicitly contrasting with resolve_comment, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use resolve_comment when only marking a thread resolved, providing a clear when-to-use vs alternative. This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true, readOnlyHint: false, and idempotentHint: false. The description adds behavioral context beyond annotations by mentioning the WebSocket wait and separate reporting of workspace-metadata and content deletion. No contradiction exists; it enriches safety understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first states the action and outcome granularity, the second provides a critical safety warning and alternative. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description covers the key decision point (when to use vs. revoke_doc), the operation's outcome reporting, and the schema fully documents all parameters. With annotations and an output schema present, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (docId, workspaceId, confirmDocId) already documented in the input schema. The description does not add parameter-level details, but the schema carries the burden effectively, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Delete a document'), the resource, and a unique behavioral detail (waiting for WebSocket outcome and reporting workspace-metadata vs content deletion separately). It explicitly distinguishes itself from revoke_doc, a sibling that removes public access only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use the tool vs. an alternative: 'use revoke_doc when you only need to remove public access.' This is a direct usage directive with a named alternative, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral detail beyond annotations: it discloses that the operation is 'Experimental', that it deletes nested folders and link nodes, and that it does not affect the underlying documents, tags, or collections. This meaningfully expands on the destructiveHint annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the action and scope, followed by clarifying consequences. Every sentence serves a purpose with no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and rich annotations, the description is sufficient. It covers the destructive scope, non-effects, and experimental status, making it complete for an AI agent to understand the tool's behavior and select it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (folderId and workspaceId) with 100% coverage. The description does not add any additional parameter-level semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('delete an AFFiNE organize folder') and clearly states the scope (every nested folder or link node). It also distinguishes itself from related tools by clarifying what it does NOT delete (target documents, tags, collections), which prevents confusion with delete_doc or delete_organize_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when this tool is appropriate (when you want to delete a folder subtree) and notes the destructive impact on sidebar organization. However, it does not explicitly mention alternatives (e.g., delete_organize_link for removing a single link) or state when NOT to use it, so it misses the 'explicit when-not' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is well-covered. The description adds meaningful behavioral context by specifying the machine-readable format and the categories of capabilities returned, which goes beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that leads with the action ('Return') and object ('capability flags'), then lists the key categories. Every word earns its place; there is no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, comprehensive annotations, and an output schema, this tool has low complexity. The description fully covers what the tool does and the scope of its response, so no additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score is 4. The description doesn't need to explain any parameter semantics, and the schema is empty. The output schema exists, so the return payload is defined elsewhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('capability flags for this MCP server'), and lists the domains covered (block, database, collaboration, export). This clearly distinguishes it from all sibling tools, which operate on workspaces, documents, or collections rather than server-level capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is a server-level capability discovery tool, which is distinct from any sibling. It doesn't explicitly state when-not-to-use or alternatives, but the scope is obvious enough that an agent would only invoke this when checking server support. The listed capability categories further suggest when it would be useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds context about what is included in the result (rules and allow-list) and confirms the read-only, non-destructive nature. This adds value beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: the first states the core action and scope, the second gives a practical prerequisite. No filler or redundancy, and both sentences earn their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with a rich output schema present, the description fully covers what the tool returns, when to use it, and the prerequisite for the id. The output schema handles return-value details, so no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already described in the schema. The description references 'by id' and mentions list_collections for obtaining the id, but does not add further parameter-level semantics. Baseline 3 applies because the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Read one AFFiNE sidebar collection by id') and states the included contents (rules and allow-list). It clearly distinguishes from siblings like list_collections by emphasizing a single collection lookup by id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Use list_collections first when the id is unknown,' which tells the agent when an alternative tool is appropriate. This is a clear when-to-use and when-not-to-use signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a read-only, idempotent, non-destructive operation. The description adds behavioral context by specifying the type of data returned (GraphQL metadata, not block content) and the specific fields included, going beyond what the annotations convey. It does not discuss error conditions or rate limits, but the added field-level detail earns a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly written sentences with no filler. The primary purpose is front-loaded in the first sentence, and the second sentence efficiently directs to a sibling tool. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward metadata read tool with two well-documented parameters, strong annotations, and an output schema, the description is complete. It covers the core function, key data fields, and provides a clear alternative when block content is needed. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully explains the docId and workspaceId parameters. The description adds no additional parameter semantics beyond the schema, which is acceptable per the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Read GraphQL metadata for one document') and lists concrete examples of the metadata (title, summary, public state, roles, timestamps). It directly distinguishes itself from the sibling tool read_doc by stating when to use the alternative, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance by saying 'Use read_doc when you need block content,' which implies get_doc is for metadata-only retrieval. This direct comparison with an alternative tool gives clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, openWorld=true, idempotent=true, destructive=false. The description adds meaningful behavioral context by specifying the exact scope of data returned (edgeless blocks, surface elements, aggregate bounding box, per-type counts) and the 'full canvas' guarantee, going beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, and every sentence adds value: what is returned, the included data, and when to use it. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description provides complete context: it names the exact content categories, the aggregate calculations, and the intended use case. The output schema covers return value details, so the description is fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions for both docId and workspaceId, so the description does not need to add parameter detail. The description does not reinforce parameter semantics, but the schema is sufficient, yielding the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('full edgeless canvas'), enumerates what is included (blocks with xywh, surface elements, bounding box, counts), and clearly distinguishes it from general read tools by focusing on the edgeless canvas layout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit usage scenario: 'Use this when you need to understand canvas layout end-to-end before placing new elements.' It gives clear context but does not mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/idempotent/destructive flags. The description adds that the tool returns collections along with their rules and specifies 'sidebar' scope, giving useful behavioral context beyond the flags. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the action and scope, the second provides usage context. No filler, redundant phrasing, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, full annotations, and an output schema, the description covers purpose, usage timing, and output scope. There are no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single workspaceId parameter with its own description. The tool description adds no parameter-specific information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List AFFiNE sidebar collections and their rules' with a specific verb (list) and resource (sidebar collections), and clarifies what is included (their rules). It distinguishes from the sibling 'get_collection' by emphasizing the plural/sidebar scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Use this read-only tool before updating, deleting, or adding documents to a collection,' providing clear when-to-use guidance. It does not name alternatives, but the context is sufficient to know when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral context beyond annotations: the operation is paginated and returns nested replies and resolution state, which clarifies the data shape. However, it does not mention default page size, sorting, or potential API quirks like offset/after interaction, so a minor gap remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the function, the second gives usage guidance. No fluff, no redundancy, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a read-only list operation with comprehensive annotations, a detailed input schema (100% coverage), and an output schema, the description is sufficient. It captures the essential purpose, the data scope (nested replies, resolution state), and when to invoke it relative to mutating comment tools. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a baseline of 3 applies. The description does not add meaning beyond the schema for parameters like after, first, offset, or workspaceId; it only says 'paginated' which is already encoded in the parameter descriptions. No extra parameter insight is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('comments for a document') and adds scope details: 'paginated', 'including nested replies and resolution state'. This distinguishes it from sibling comment mutation tools like create_comment, update_comment, delete_comment, and resolve_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use this before update_comment, delete_comment, or resolve_comment when you need the existing comment ids.' This names specific alternatives and provides a clear usage context, fulfilling the when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context about the WebSocket snapshot mechanism and the optional markdown output, enriching the behavioral model without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and output format, and each clause serves a purpose. It explains the optional parameter with a practical rationale without extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and strong annotations, the description sufficiently covers the tool's purpose, method (WebSocket snapshot), output format, and its relationship to a sibling tool. No critical information gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds meaning to includeMarkdown by linking it to rendered markdown and the equivalent export_doc_markdown call, going beyond the schema's simple boolean description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads document block content via a WebSocket snapshot, including blocks and plain text. It also distinguishes itself from export_doc_markdown by noting that includeMarkdown can obviate that separate call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly references export_doc_markdown as an alternative and explains when to use includeMarkdown, giving a concrete usage scenario. It does not exhaustively compare to other sibling read tools like get_doc, but the primary context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds the key behavioral fact that it does not delete the document, which is valuable context beyond the annotations. However, it does not mention whether the action is reversible or what happens to existing shares, so 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action and a key exclusion. Every word earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple revoke operation with an output schema, the description is complete: it states what the tool does, what it does not do, and when to use an alternative. No missing critical information for this tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema documentation covers 100% of the parameters (docId and workspaceId) with clear descriptions. The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Disable public sharing for a document' with the specific resource (document). It also distinguishes itself from delete_doc by noting 'without deleting the document,' making the purpose unambiguous and differentiating it from a sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance with an alternative: 'Use delete_doc only when the document itself should be removed.' This tells the agent when to use this tool versus delete_doc, which is a clear usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds valuable context beyond annotations by noting it preserves the comment thread, which clarifies its non-destructive nature. It doesn't detail auth requirements or rate limits, but the added context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately front-loaded with the verb 'Replace,' and the second sentence adds an alternative without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with only 2 parameters and an existing output schema, this description fully covers what the tool does, when to use it, and its key behavioral nuance (preserving the thread). The output schema handles return values, and the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already well-described ('Comment id returned by list_comments or create_comment' and 'Replacement comment content accepted by AFFiNE'). The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Replace the content of an existing comment') with a specific verb and resource. It also distinguishes from create_comment by noting that it preserves the thread, making the tool's unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (to replace content of an existing comment) and when to use an alternative ('use create_comment for a new thread'). This provides clear contextual guidance versus its sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds valuable context: it reads workspace metadata (fast, no per-doc fetch), default case-sensitivity, and the use of `caseInsensitive` to fold case. These are behavioral traits not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the purpose first, then behavior, comparison, recommendation, and return shape. Every sentence provides useful information, though it is slightly longer than necessary given the output schema already exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter list, full schema coverage, an output schema, and thorough annotations, the description fully contextualizes the tool. It covers purpose, usage guidance, behavioral nuances, and return format, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the default and max for `limit` (50/200) and the effect of `caseInsensitive` (folds case), going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Resolve docs by exact title,' using a specific verb and resource. It clearly distinguishes this tool from `search_docs` by contrasting case-sensitivity and limit behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to prefer this tool over `search_docs` ('Prefer this over `search_docs` when you know the exact title and want every match') and provides key differentiators like case sensitivity and limit caps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavior: fallback when GraphQL is denied, inTrash flag, null values in fallback, and non-interchangeable cursors. This goes well beyond annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the core purpose. Every sentence adds critical information: the operation, fallback behavior, output field nuances, and cursor handling. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema fully documents parameters and an output schema exists, the description covers the essential behavioral context: fallback, flags, null semantics, and pagination restart. It is complete for a list tool with this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3, but the description adds important pagination nuance about GraphQL and fallback cursors not being interchangeable and the need to restart pagination without 'after' on rejected cursors. This directly enhances the meaning of the 'after' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'List documents in a workspace', clearly defining its scope and distinguishing it from siblings like list_workspaces, list_tags, and list_docs_by_tag. The mention of GraphQL and fallback behavior further clarifies the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies when the tool is called with GraphQL and when it falls back to workspace metadata if GraphQL access is denied, giving clear context. It does not explicitly name alternatives or exclusions, but the usage context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by revealing merge vs replace behavior and the response `ignored` list for non-applicable fields. Annotations already signal non-read-only, non-idempotent, non-destructive; the description provides concrete update behavior without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with clear structure: what it does, merge vs replace, and ignored fields. No filler or redundant restatement of schema defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 30-parameter tool, the description covers the core update semantics (merge/replace, ignored fields) and benefits from having an output schema. It doesn't enumerate all params, but the schema already does; the description adds the behavioral glue needed to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description enriches parameters by grouping x/y/width/height as mergeable and text/label/title as wholesale replacements, and explains type-specific field handling via the ignored list. This adds cross-parameter meaning but individual param details remain in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('Partially update a surface element by id'), clearly distinguishing this from sibling tools like add_surface_element, delete_surface_element, and list_surface_elements. It also accurately describes merge vs replace semantics, removing ambiguity about partial updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by defining partial update semantics (merge xywh, replace text/label/title) and noting type-inapplicable fields are ignored. However, it does not explicitly name alternatives or when-not-to-use conditions, relying on the sibling tool list and tool name to differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently discloses the partial-update merge behavior for x/y/width/height, the replacement behavior for background, and the fact that non-applicable fields are returned under 'ignored'. This goes beyond the minimal annotations and is valuable for an agent deciding on impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each packed with meaning: purpose, merge semantics, and ignored-field behavior. No fluff or repetition, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of partial updates and the output schema, the description covers all essential behavioral aspects: what merges, what replaces, and how inapplicable fields are handled. No significant gaps remain beyond what the schema and annotations already provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite only 50% schema description coverage, the description thoroughly explains the undocumented x/y/width/height parameters (merge with current xywh) and clarifies the background format and block flavour constraints. This effectively compensates for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Partially update') and resource ('note/frame/edgeless-text block by id'), clearly distinguishing it from other update tools by naming the exact block types. It also explains the merge behavior, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (updating edgeless blocks with partial semantics) but does not explicitly name alternatives or state when not to use it. The mention of specific block flavours implies the scope, but lacks an explicit exclusion of other block types or tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations by disclosing the internal prop (childElementIds), behavior for unresolved ids ('missing'), the automatic resizing logic, and the effect of passing an empty array. This gives the agent a clear model of side effects and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, front-loading the core action before explaining edge cases. Every sentence adds value, and the structure flows logically from purpose to behavior to parameter nuances.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple block types, ownership, resizing), the description covers all essential behaviors, including edge cases like missing ids and clearing ownership. With output schema present and annotations provided, the description is fully adequate for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Though the schema covers all parameters, the description adds critical semantics: it explains the meaning of childElementIds as a full replacement list, clarifies padding's role, and specifies that resize is skipped when passing an empty array. This enriches the bare schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Replace a frame block's contents wholesale.' It clearly states what the tool does and distinguishes it from related tools like update_edgeless_block by focusing on frame ownership semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context by explaining how the tool mimics editor behavior when dragging members into a frame, and when to use resizeToFit=false. However, it does not explicitly name sibling alternatives or state when-not-to-use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations flag destructiveHint=true and openWorldHint=true, but the description adds concrete effect details: removes descendants, unlinks from parent's sys:children by default, optionally prunes surface connectors referencing deleted ids. It also notes refusal of affine:page. This goes well beyond the annotation-level disclosure and sets clear expectations for side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences: core action, key options, and exclusion. Each sentence is information-dense and earns its place, with no fluff or repetition. It is front-loaded with the primary action and efficiently packs behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5-parameter schema, an output schema, and annotations, the description covers deletion side effects, parameter behavior, and the key alternative. It leaves no critical ambiguity about what the tool does, when to use it, and what consequences to expect. This is complete 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already described. The description enriches deleteChildren with the 'for re-parenting' use case and clarifies that pruneConnectors removes connectors referencing any deleted id. While the schema explains the flags, the description adds semantic context that helps an agent choose appropriate parameter values. This exceeds the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a block by id', a specific verb+resource statement. It then details the deletion semantics (descendants, parent sys:children, connectors) and explicitly distinguishes from delete_doc by stating 'Refuses affine:page — use delete_doc for whole docs.' This clearly identifies the tool's function and differentiates it from sibling delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'use delete_doc for whole docs,' providing an exclusion and alternative. It also gives conditional usage guidance: setting deleteChildren=false for re-parenting, and pruneConnectors=true to also drop surface connectors. This tells the agent when to use the tool and how to adjust behavior for specific needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![affine-mcp-server MCP server](https://glama.ai/mcp/servers/irfanhak123/affine-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/irfanhak123/affine-mcp-server)

Score Badge

Copy to your README.md:

[![affine-mcp-server MCP server](https://glama.ai/mcp/servers/irfanhak123/affine-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/irfanhak123/affine-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/irfanhak123/affine-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server