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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it's a mutation operation (implied by 'Appends'), it adds content without replacing existing content, and it accepts TipTap XML for various block types. However, it lacks details on permissions, error conditions, rate limits, or what happens if the document doesn't exist. The description does not contradict any annotations (since none exist).

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

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

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by essential details about input format and usage context. Every sentence earns its place by providing necessary information without redundancy or fluff.

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

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

Given the complexity (a mutation tool with 3 parameters, no annotations, and no output schema), the description is partially complete. It adequately covers the tool's purpose and input format but lacks information on prerequisites (e.g., required permissions), error handling, response format, or side effects. Without annotations or output schema, more behavioral context would be beneficial for safe invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that the 'text' parameter accepts 'TipTap XML for any block type' and provides examples (e.g., '<paragraph>text</paragraph>', '<heading level="2">Title</heading>'), adding crucial semantic meaning beyond the schema's generic 'Text' title. However, it does not clarify the semantics of 'graph_id' or 'document_id' parameters, leaving them undocumented.

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

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

The description clearly states the specific action ('Appends a block to the end of a document') and resource ('document'), distinguishing it from siblings like 'insert_block' (which might insert at arbitrary positions) or 'write_document' (which might replace content). It explicitly mentions 'incremental additions without replacing existing content' to further differentiate.

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

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

The description provides clear context on when to use this tool ('for incremental additions without replacing existing content') and gives examples of acceptable content types (plain text vs. structured XML). However, it does not explicitly state when NOT to use it or name specific alternatives among the sibling tools (e.g., 'insert_block' for non-append insertions, 'update_block' for modifications, or 'write_document' for full replacements).

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

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

No annotations are provided, so the description carries full burden. It mentions transactional behavior ('single transaction') and efficiency, but lacks critical details: it doesn't specify permissions required, whether updates are atomic or partial, error handling for failed updates, or rate limits. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.

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

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

The description is highly concise and well-structured: three sentences that efficiently cover purpose, efficiency benefit, parameter details, and return value. Every sentence adds value without redundancy, and key information is front-loaded.

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

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

Given the tool's complexity (batch mutation with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain the return format ('results for each update' is vague), error scenarios, or provide enough parameter guidance. For a mutation tool with zero structured support, this leaves too many gaps for reliable agent use.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'attributes to change and/or new XML content' for updates, which adds some meaning to the 'updates' parameter. However, it doesn't explain 'graph_id' or 'document_id' parameters at all, leaving two of three parameters semantically unclear. The partial coverage is insufficient.

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

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

The description clearly states the tool's purpose: 'Update multiple blocks in a single transaction.' It specifies the resource (blocks) and verb (update), and distinguishes it from 'update_block' by highlighting batch efficiency. However, it doesn't explicitly differentiate from other sibling tools like 'write_document' or 'sparql_update' that might also modify content.

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

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

The description provides clear context for usage: 'More efficient than individual update_block calls.' This explicitly positions it as an alternative to 'update_block' for bulk operations. It doesn't specify when NOT to use it or mention other alternatives like 'write_document', but the efficiency guidance is helpful.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the creation action and some organizational aspects (nesting, sidebar section), but doesn't address important behavioral traits like: what permissions are required, whether folder creation is reversible (can folders be deleted?), what happens if a folder with the same ID already exists, or what the response format looks like. For a mutation tool with zero annotation coverage, this represents significant gaps.

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

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

The description is efficiently structured in two sentences that each add value. The first sentence states the core purpose, and the second sentence provides important usage context for two key parameters. There's no wasted language or redundancy, and the most critical information appears first.

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

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

For a mutation tool with 6 parameters, 0% schema description coverage, no annotations, and no output schema, the description is insufficiently complete. It covers the basic creation action and two parameters but leaves critical gaps: no information about required permissions, error conditions, response format, or the purpose of most parameters. The agent would struggle to use this tool correctly without additional context.

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

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

With 0% schema description coverage for all 6 parameters, the description must compensate but only partially succeeds. It explains parent_id ('to nest inside another folder (null for root level)') and section ('determines which sidebar section the folder appears in'), covering 2 of 6 parameters. However, it doesn't explain the purpose of graph_id, folder_id, label, or order parameters, leaving most parameters without semantic context beyond their schema titles.

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

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

The description clearly states the action ('Create a new folder') and the resource ('in the workspace'), making the purpose immediately understandable. It distinguishes from siblings like 'create_graph' by specifying folder creation rather than graph creation. However, it doesn't explicitly differentiate from 'move_folder' or 'rename_folder' which also involve folder operations.

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

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

The description provides some implicit usage guidance by explaining how to use parent_id for nesting and mentioning the section parameter for sidebar placement. However, it doesn't explicitly state when to use this tool versus alternatives like 'move_folder' for reorganizing existing folders or 'create_graph' for creating different resource types. No explicit when-not-to-use guidance is provided.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions the tool creates something (implying mutation), it doesn't address important behavioral aspects like permissions required, whether the operation is idempotent, what happens on duplicate graph_id, rate limits, or what the output contains. The description provides minimal behavioral context beyond the basic operation.

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

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

Two sentences with zero waste. The first sentence states the core purpose and parameters. The second provides crucial formatting guidance for graph_id. Every word earns its place, and the most important information (what it creates) comes first.

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

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

Given this is a mutation tool with no annotations but with an output schema (which handles return values), the description is moderately complete. It covers the parameters well but lacks behavioral context about permissions, idempotency, and error conditions. For a creation tool, more guidance on duplicate handling and success criteria would be beneficial.

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

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

With 0% schema description coverage, the description compensates well by explaining all 3 parameters: graph_id (URL-safe identifier with examples), title, and description (optional). It adds meaningful context about the graph_id format that isn't in the schema, though it doesn't elaborate on title constraints or description content guidelines.

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

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

The description clearly states the verb 'creates' and resource 'knowledge graph' with specific attributes (ID, title, optional description). It distinguishes from siblings like 'delete_graph' or 'list_graphs' by focusing on creation, but doesn't explicitly contrast with similar tools like 'create_folder' beyond the resource type.

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

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

No guidance on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites, when this operation is appropriate, or what happens if a graph with the same ID already exists. It simply states what the tool does without contextual usage information.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the destructive nature ('Delete'), the cascade effect for children blocks, and the return value ('Returns the list of deleted block IDs'). This covers the core behavior, though it doesn't mention permissions, error conditions, or rate limits, which would enhance transparency further.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by parameter guidance and return value in subsequent sentences. Each sentence earns its place by adding value: defining the action, explaining a key parameter, and stating the output. No wasted words, and it's 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.

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

Given no annotations, 0% schema coverage, and no output schema, the description provides a basic but incomplete picture. It covers the destructive behavior and cascade effect, which is essential, but lacks details on permissions, error handling, or the structure of the returned list. For a mutation tool with multiple parameters, more context would be beneficial to ensure safe and correct usage.

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

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

The schema description coverage is 0%, so the description must compensate. It adds meaning for the 'cascade' parameter by explaining its effect ('to also delete all subsequent blocks with higher indent'), which is crucial beyond the schema's basic type. However, it doesn't clarify the semantics of 'graph_id', 'document_id', or 'block_id', leaving those parameters undocumented in both schema and description.

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

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

The description clearly states the action ('Delete a block by its ID') and resource ('block'), which is specific and unambiguous. It distinguishes from siblings like 'delete_folder' or 'delete_graph' by specifying the resource type. However, it doesn't explicitly differentiate from 'update_block' or 'batch_update_blocks' in terms of destructive intent beyond the verb 'Delete'.

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

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

The description provides implied usage guidance by mentioning the 'cascade' parameter effect ('to also delete all subsequent blocks with higher indent'), which suggests when to use this option. However, it lacks explicit when-to-use vs. alternatives (e.g., compared to 'delete_graph' or 'update_block' for partial modifications), and no prerequisites or exclusions are stated.

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

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

With no annotations provided, the description carries full burden and does well by disclosing critical behavioral traits: it's a destructive operation (implied by 'Delete'), specifies failure conditions ('deletion fails if the folder has children'), and explains the cascade parameter's effect on subfolders/documents/artifacts. It doesn't mention permissions, rate limits, or reversibility, which keeps it from a perfect score.

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

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

Two sentences, front-loaded with the core purpose, followed by parameter-specific guidance. Every word earns its place—no fluff, no repetition, efficiently covering both the action and critical behavioral nuance.

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

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

For a destructive tool with 3 parameters, 0% schema coverage, and no output schema, the description is quite complete—it explains the core operation, failure conditions, and key parameter. It doesn't cover return values or error formats, but given the straightforward nature of a delete operation, this is a minor gap.

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

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

With 0% schema description coverage, the description fully compensates by explaining the 'cascade' parameter's semantics in detail (what happens when true/false). It doesn't explain 'graph_id' or 'folder_id', but given the tool's name and context, their purpose is reasonably inferable, and the cascade explanation adds significant value beyond the bare schema.

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

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

The description clearly states the specific action ('Delete a folder from the workspace') and distinguishes it from siblings like 'delete_graph' or 'delete_block' by specifying the resource type. It uses precise language that leaves 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.

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

The description provides clear context about when to use cascade=true vs. not (when folder has children), but doesn't explicitly mention when to use this tool versus alternatives like 'delete_graph' or 'move_folder'. It gives operational guidance but lacks sibling differentiation.

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

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

With no annotations provided, the description carries the full burden and effectively discloses key behavioral traits: it's a destructive operation ('permanently deletes'), irreversible ('cannot be undone'), and has broad impact ('all its contents'). However, it omits details like permissions needed, rate limits, or error conditions, which would enhance transparency for a mutation tool.

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

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

The description is front-loaded with the core action in the first sentence, followed by critical warnings, with no wasted words. Every sentence ('Permanently deletes...', 'This action cannot be undone.', 'Use with caution.') earns its place by adding essential context efficiently.

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

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

Given the tool's complexity (destructive mutation), lack of annotations, and 0% schema coverage, the description is incomplete. It covers the irreversible nature but misses parameter details, permissions, or output expectations. The presence of an output schema helps, but the description should do more to compensate for the sparse structured data.

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

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

Schema description coverage is 0%, so the description must compensate, but it adds no information about the 'graph_id' parameter beyond what the schema's title implies. The description does not explain what a graph_id is, its format, or how to obtain it, leaving the parameter's meaning unclear despite the low coverage.

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

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

The description clearly states the specific action ('permanently deletes') and resource ('a knowledge graph and all its contents'), distinguishing it from siblings like delete_block or delete_folder which target different resources. It precisely communicates the tool's function without ambiguity.

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

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

The description provides clear context with 'Use with caution' and implies usage for irreversible deletion, but does not explicitly state when to use this versus alternatives like delete_block or delete_folder, or any prerequisites. It offers general warning but lacks specific comparative guidance.

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

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

With no annotations provided, the description carries full burden. It discloses that user_id is 'automatically derived from authentication if not provided,' which is useful behavioral context about default behavior. However, it doesn't describe what happens if no active session exists, whether this is a read-only operation, or what the return format looks like.

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

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

Two sentences, front-loaded with core purpose, followed by usage guidance and parameter clarification. Every sentence earns its place with no wasted words or redundancy.

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

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

For a simple read operation with 1 parameter and no output schema, the description covers purpose and usage well. However, without annotations or output schema, it should ideally mention that this is a read-only operation and hint at the return structure (e.g., returns IDs as strings). The current description is adequate but has gaps in behavioral disclosure.

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

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

The description adds meaningful context about the single parameter: 'The user_id is automatically derived from authentication if not provided.' This explains the optional nature and default behavior beyond what the schema shows (just 'User Id' with null default). With 0% schema description coverage and only 1 parameter, this adequately compensates.

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

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

The description clearly states the specific action ('Returns'), resources ('currently active graph ID and document ID'), and context ('from the user's session'). It distinguishes from siblings like 'get_block' or 'get_workspace' by focusing on session-specific active context rather than retrieving arbitrary resources.

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

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

Explicitly states when to use this tool: 'Use this to understand what the user is currently working on in the Mnemosyne UI.' This provides clear context for application versus alternatives like 'list_graphs' for general listing or 'read_document' for document content.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is a read operation (implied safe) and describes the return content (XML, attributes, text, context), which is helpful. However, it lacks details on permissions, error handling, rate limits, or whether it's idempotent, leaving behavioral gaps.

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

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

The description is front-loaded with the core purpose, followed by return details and usage context in two efficient sentences. Every sentence adds value without redundancy, making it appropriately sized and well-structured.

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

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

Given no annotations, no output schema, and 3 required parameters with 0% schema coverage, the description is incomplete. It covers the purpose and return content well but fails to explain parameter meanings or full behavioral traits, leaving gaps for a tool with multiple inputs.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions 'data-block-id' (likely referring to block_id), but does not explain the purpose or relationships of graph_id and document_id parameters. This leaves two of three parameters semantically unclear.

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

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

The description clearly states the verb ('Read') and resource ('a specific block by its data-block-id'), distinguishing it from siblings like query_blocks (which likely searches/filters) or read_document (which fetches entire documents). It specifies the targeted nature of the operation.

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

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

The description provides clear context for when to use this tool ('for targeted reads without fetching the entire document'), implicitly contrasting with read_document. However, it does not explicitly state when not to use it or name alternatives, missing full explicit guidance.

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

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

No annotations are provided, so the description carries full burden. It states it 'Returns' data, implying a read-only operation, but does not disclose behavioral traits such as permissions required, rate limits, pagination, or response format. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.

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

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

The description is two sentences, front-loaded with the core purpose and followed by usage context. Every sentence adds value without redundancy, making it efficient and well-structured for quick comprehension.

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

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

Given 1 parameter with 0% schema coverage, no annotations, and no output schema, the description is incomplete. It covers the basic purpose but lacks details on parameters, behavioral traits, or return values, which are essential for a tool that retrieves structural data in a graph-based system.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'graph's workspace' but does not explain the 'graph_id' parameter beyond what the schema title ('Graph Id') provides. No details on format, sourcing, or constraints are added, failing to adequately clarify parameter meaning.

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

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

The description clearly states the verb ('Returns') and resource ('folder and file structure of a graph's workspace'), specifying it provides organizational understanding. It distinguishes from siblings like 'list_graphs' (which lists graphs) or 'get_block' (which retrieves individual blocks), but could be more explicit about the distinction.

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

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

The description implies usage ('Use this to understand the organization of documents in a graph') for exploring workspace structure, but lacks explicit guidance on when to choose this over alternatives like 'list_graphs' for high-level overview or 'query_blocks' for detailed content. No exclusions or prerequisites are mentioned.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns the new block's generated ID, which is useful behavioral information. However, it lacks details on permissions, error conditions, or mutation effects beyond the basic operation. The description doesn't contradict annotations (none exist).

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

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

The description is front-loaded with the core purpose, followed by parameter guidance and alternative usage. Every sentence earns its place: the first states the action, the second explains parameter usage, and the third provides sibling differentiation. No wasted words.

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

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

Given the tool's complexity (5 parameters, mutation operation) and lack of annotations/output schema, the description is moderately complete. It covers the basic operation and sibling differentiation but misses details on parameter meanings beyond 'position', error handling, and return format specifics. It's adequate but has clear gaps for a mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'position' parameter's semantics ('after' or 'before'), which adds meaning beyond the schema's basic type definition. However, it doesn't clarify the purpose of other parameters like 'graph_id', 'document_id', 'reference_block_id', or 'xml_content', leaving gaps in understanding.

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

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

The description clearly states the specific action ('Insert a new block relative to an existing block') and distinguishes it from a sibling tool ('For appending to the end, use append_to_document instead'). It specifies both the verb (insert) and resource (block) with context about positioning.

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

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

The description provides explicit guidance on when to use this tool vs. alternatives: it specifies to use 'append_to_document' for appending to the end, and implies usage for inserting relative to existing blocks. This clearly differentiates from sibling tools like 'append_to_document' and 'batch_update_blocks'.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns metadata (IDs, titles, timestamps) and is scoped to the authenticated user's graphs, which is useful context. However, it omits behavioral details like pagination, rate limits, error handling, or whether the list is sorted/filtered beyond ownership.

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

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

The description is two sentences with zero waste: the first states the purpose and scope, the second specifies the return data. It is front-loaded with the core functionality and efficiently structured without redundant information.

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

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

Given the tool's low complexity (0 parameters, simple list operation) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers ownership scope and metadata types, but could improve by addressing behavioral aspects like ordering or limitations, though the output schema mitigates this gap.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately adds no parameter details, focusing instead on the tool's purpose and output. This aligns with the baseline for zero parameters, though it doesn't explicitly state the lack of parameters.

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

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

The description clearly states the verb ('Lists') and resource ('all knowledge graphs owned by the authenticated user'), specifying both scope and ownership. It distinguishes from siblings like 'create_graph' (creation) and 'delete_graph' (deletion) by focusing on retrieval of existing graphs.

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

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

The description implies usage for retrieving graph metadata, but lacks explicit guidance on when to use this versus alternatives like 'query_blocks' or 'sparql_query' for more specific queries. No exclusions or prerequisites are mentioned, leaving usage context somewhat open-ended.

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

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

With no annotations provided, the description carries full burden but reveals minimal behavioral traits. It states the tool moves artifacts and allows null parent_id for root, but doesn't disclose permission requirements, whether the move is destructive/reversible, rate limits, or what happens to artifact relationships. For a mutation tool with zero annotation coverage, this is inadequate.

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

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

The description is extremely concise with two sentences that directly address core functionality and a key parameter nuance. Every word earns its place with zero waste or redundancy.

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

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

For a mutation tool with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It doesn't explain return values, error conditions, permission requirements, or how it differs from similar sibling tools like 'move_document' and 'move_folder'.

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

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

Schema description coverage is 0%, so the description must compensate but only adds meaning for 'new_parent_id' (null moves to root). It doesn't explain 'graph_id', 'artifact_id', or 'new_order' parameters. With 4 parameters total and only 1 partially clarified, this meets the baseline for minimal compensation.

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

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

The description clearly states the verb ('Move') and resource ('an artifact'), specifying the action of relocating to a different folder. It distinguishes from siblings like 'move_document' and 'move_folder' by focusing on artifacts, but doesn't explicitly contrast with 'rename_artifact' or other artifact-related tools.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'move_document', 'move_folder', or 'rename_artifact'. It mentions moving to root level with null parent_id, but offers no context about prerequisites, error conditions, or sibling tool distinctions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool 'updates the document's folder assignment,' implying a mutation, but fails to disclose critical behavioral traits such as required permissions, whether the move is reversible, potential side effects (e.g., impact on linked content), or error conditions. This leaves significant gaps for an AI agent to understand the tool's behavior.

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

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

The description is appropriately sized and front-loaded, with the core purpose stated first ('Move a document to a folder'), followed by a usage note and behavioral detail. Every sentence earns its place by adding value, and there is no redundant or verbose language.

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

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

Given the complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It covers the basic purpose and one parameter nuance but lacks details on permissions, error handling, return values, or side effects. While concise, it does not provide enough context for safe and effective use by an AI agent.

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

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

The schema description coverage is 0%, so the description must compensate. It adds meaning for 'new_parent_id' by explaining that setting it to null moves the document to root level, which clarifies the parameter's semantics beyond the schema. However, it does not provide context for 'graph_id' or 'document_id,' leaving two of the three parameters without additional explanation, resulting in a baseline score.

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

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

The description clearly states the specific action ('Move a document to a folder') and resource ('document'), distinguishing it from siblings like move_folder or move_artifact. It also specifies the scope of the operation ('updates the document's folder assignment in workspace navigation'), 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.

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

The description provides clear context on when to use this tool ('Move a document to a folder') and includes a specific usage note ('Set new_parent_id to null to move to root level (unfiled)'). However, it does not explicitly state when not to use it or mention alternatives like move_folder for different resource types, which prevents a perfect score.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the action ('Move') and optional ordering, but fails to address critical aspects like permissions required, whether the operation is reversible, error conditions, or what happens to child items. This is inadequate for a mutation tool.

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

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

The description is efficiently structured in two sentences with zero waste. The first sentence states the core purpose, and the second provides essential usage details for parameters. Every element adds value.

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

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

Given the complexity of a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description is incomplete. It lacks information on permissions, side effects, error handling, and return values, which are critical for safe and effective use.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaningful context for 'new_parent_id' (null for root) and 'new_order' (positioning among siblings), clarifying their purposes beyond the schema's basic titles. However, it does not explain 'graph_id' or 'folder_id' parameters.

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

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

The description clearly states the specific action ('Move a folder') and resource ('to a new parent folder'), distinguishing it from sibling tools like 'rename_folder' or 'delete_folder'. It precisely defines the tool's function with no ambiguity.

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

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

The description provides clear context for usage ('Set new_parent_id to null to move to root level') but does not explicitly mention when to use this tool versus alternatives like 'move_document' or 'move_artifact'. It offers operational guidance but lacks sibling differentiation.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns 'a list of matching block summaries,' which is helpful context about output format. However, it doesn't mention pagination behavior (though 'limit' parameter is in schema), error conditions, or performance characteristics. The description adds some value but lacks comprehensive behavioral details.

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

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

The description is efficiently structured in two sentences: the first explains what the tool does and its filtering capabilities, the second states the return type and primary use case. Every word earns its place with no redundancy or unnecessary elaboration.

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

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

For a search tool with 10 parameters, 0% schema description coverage, and no output schema, the description provides adequate but incomplete context. It explains the core filtering logic and use case but doesn't cover all parameters or provide details about the 'block summaries' structure. Given the complexity, more comprehensive documentation would be beneficial.

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

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

The description lists specific filter criteria ('block type, indent level, list type, checked state, or text content'), which maps to 5 of the 10 parameters. With 0% schema description coverage, this adds significant value beyond the bare schema. However, it doesn't explain the relationship between 'indent' vs 'indent_gte/lte' parameters or mention 'graph_id' and 'document_id' requirements.

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

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

The description clearly states the specific action ('Search for blocks matching specific criteria') and resource ('blocks'), distinguishing it from siblings like 'get_block' (single block retrieval) or 'read_document' (full document reading). It explicitly mentions the purpose is to 'find blocks without reading the entire document,' which differentiates it from document-level operations.

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

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

The description provides explicit guidance on when to use this tool ('to find blocks without reading the entire document') and implies when not to use it (for reading entire documents or retrieving single blocks). It distinguishes this search-focused tool from alternatives like 'get_block' (for single blocks) and 'read_document' (for full documents).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the output format (TipTap XML) and supported elements (blocks, marks, lists), which helps the agent understand what to expect. However, it lacks details on permissions, rate limits, error handling, or whether the operation is idempotent, leaving gaps for a mutation-free read tool.

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

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

The description is appropriately sized and front-loaded, starting with the core purpose. The detailed formatting examples are useful but could be more structured; however, every sentence adds value by clarifying output semantics, avoiding waste.

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

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

Given the tool's complexity (read operation with specific output format), no annotations, no output schema, and low schema coverage, the description is partially complete. It excels in explaining the return format but fails to cover parameters or broader behavioral context, making it adequate but with clear gaps.

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

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

The description adds no meaning beyond the input schema, which has 0% description coverage. Parameters 'graph_id' and 'document_id' are undocumented in both schema and description, leaving their purpose, format, and sourcing unclear. For a tool with two required parameters, this is a significant deficiency.

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

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

The description clearly states the specific action ('Reads document content') and resource ('document'), distinguishing it from siblings like 'write_document', 'append_to_document', or 'get_block' by specifying the output format as TipTap XML with full formatting. It goes beyond a simple read operation by detailing what content is retrieved.

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

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

No guidance is provided on when to use this tool versus alternatives like 'get_block' or 'query_blocks'. The description focuses on output format but does not mention prerequisites, context, or exclusions, leaving the agent to infer usage based on sibling tool names alone.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool performs a rename operation but doesn't specify whether this requires specific permissions, if the change is reversible, what happens to references to the artifact, or what the response looks like. This leaves significant gaps for a mutation tool.

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

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

The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple rename operation.

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

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

For a mutation tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain parameter meanings, behavioral implications, or what to expect after invocation, leaving the agent with insufficient context.

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

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

Schema description coverage is 0%, so the schema provides only parameter names without meaning. The description mentions 'artifact's display label' which hints at 'new_label' but doesn't explain 'graph_id' or 'artifact_id' parameters. It adds minimal value beyond what's inferable from the tool name.

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

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

The description clearly states the verb ('rename') and resource ('artifact's display label'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'rename_folder', which performs a similar operation on a different resource type.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'move_artifact' or 'update_block', nor does it mention prerequisites or constraints. The agent must infer usage 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.

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Rename' implies a mutation operation, but the description doesn't state whether this requires specific permissions, whether the change is reversible, what happens to references to the old label, or if there are rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in 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.

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

The description is a single, efficient sentence that front-loads the core action. Every word earns its place with no redundancy or fluff. It's appropriately sized for a straightforward operation like renaming.

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

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

Given the tool's complexity (a mutation with 3 parameters), lack of annotations, 0% schema description coverage, and no output schema, the description is incomplete. It doesn't explain parameter meanings, behavioral implications, error conditions, or what the tool returns. The agent lacks sufficient context to use this tool effectively without guessing.

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

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

Schema description coverage is 0%, meaning none of the three parameters (graph_id, folder_id, new_label) are documented in the schema. The description only mentions 'a folder's display label', which loosely relates to 'new_label' but doesn't explain what graph_id or folder_id are, their formats, or how to obtain them. The description adds minimal value beyond the schema.

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

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

The description clearly states the action ('Rename') and the resource ('a folder's display label'), making the purpose immediately understandable. It distinguishes from siblings like 'create_folder' or 'delete_folder' by focusing on modification rather than creation or deletion. However, it doesn't explicitly differentiate from 'rename_artifact' which might be a similar operation on a different resource type.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing folder), when not to use it, or how it differs from similar tools like 'rename_artifact' or 'move_folder'. The agent must infer usage 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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates that this is a read-only operation (important safety context) and specifies the query types supported (SELECT/CONSTRUCT). However, it doesn't mention potential limitations like query timeout, result size limits, authentication requirements, or error handling. The description adds useful context but leaves significant behavioral aspects unspecified.

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

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

The description is perfectly concise with three tightly focused sentences: the first states the core functionality, the second specifies the return format, and the third provides usage guidance. Every sentence earns its place with no wasted words, and the most important information (read-only query execution) is front-loaded.

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

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

Given the tool's moderate complexity (SPARQL queries can be complex), no annotations, and an output schema that presumably documents the return structure, the description covers the essential aspects: purpose, read-only nature, supported query types, and basic usage. However, the complete lack of parameter documentation (0% schema coverage with no compensation in the description) prevents a perfect score, as users need to understand what constitutes valid SPARQL syntax.

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

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

With 0% schema description coverage for both parameters, the description provides no additional semantic information about the 'sparql' parameter (what constitutes a valid SPARQL query) or 'result_format' parameter (what formats are supported beyond the default 'json'). The description mentions JSON output but doesn't clarify if this relates to the result_format parameter or is fixed behavior. The description fails to compensate for the complete lack of schema documentation.

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

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

The description clearly states the specific action ('Executes'), resource ('SPARQL SELECT or CONSTRUCT query against the user's graphs'), and distinguishes it from sibling tools by specifying it's for read-only queries (unlike sparql_update which presumably handles updates). It explicitly mentions the return format ('Returns query results as JSON') and primary use case ('searching and retrieving data from graphs').

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

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

The description provides explicit guidance on when to use this tool ('for searching and retrieving data from graphs') and implicitly when not to use it (since it's 'read-only' and only handles SELECT/CONSTRUCT queries, suggesting sparql_update should be used for modifications). It clearly differentiates from the sparql_update sibling tool without needing to name it directly.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it states this is for modification operations, it doesn't disclose important behavioral traits like whether this requires specific permissions, whether changes are reversible, what happens on failure, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in behavioral transparency.

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

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

The description is extremely concise with just two sentences that each earn their place. The first sentence states the core functionality, and the second provides usage guidance. There's zero waste or redundancy in the text.

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

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

Given this is a mutation tool with no annotations, 0% schema description coverage, but with an output schema present, the description is moderately complete. It covers the purpose and basic usage but lacks important behavioral context about permissions, side effects, and error handling that would be crucial for safe tool invocation.

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

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

The description doesn't provide any parameter-specific information beyond what's implied by the tool's purpose. With 0% schema description coverage and only one parameter, the baseline would be 4 for zero parameters, but since there is one parameter with no description in either schema or tool description, this drops to 3. The description doesn't explain what format the SPARQL query should take or provide examples.

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

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

The description clearly states the specific verb ('executes') and resource ('SPARQL INSERT, DELETE, or UPDATE operation'), and distinguishes it from sibling tools by specifying it's for modifying graph data rather than querying (sparql_query) or other operations like creating/deleting graphs. It explicitly mentions the types of operations supported (INSERT, DELETE, UPDATE).

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

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

The description provides explicit guidance on when to use this tool ('for adding, modifying, or removing triples from graphs') and implicitly distinguishes it from sparql_query (which would be for querying rather than modifying). It clearly indicates this is for data modification operations rather than read operations.

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

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

With no annotations provided, the description carries the full burden. It discloses that this is a mutation operation ('Update', 'edit') and describes the scope of changes ('without changing content' or 'replace the entire block content'), but doesn't mention permissions needed, whether changes are reversible, error conditions, or response format. It adds some behavioral context but leaves significant gaps.

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

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

The description is perfectly front-loaded and concise with three sentences that each earn their place: first states the core action, second explains the two update modes, third emphasizes the surgical nature. Zero wasted words.

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

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

Given a mutation tool with 5 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It covers purpose and some parameter semantics but lacks behavioral details (permissions, reversibility), full parameter explanations, and output information. It's adequate as a minimum viable description but has clear gaps for this complexity level.

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

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

With 0% schema description coverage for 5 parameters, the description must compensate but only partially does so. It mentions 'attributes (indent, checked, listType)' and 'xml_content' for content replacement, explaining their purpose, but doesn't address graph_id, document_id, or block_id parameters. The description adds meaning for 2 of 5 parameters, insufficient compensation for the coverage gap.

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

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

The description clearly states the verb ('Update') and resource ('a block by its ID'), and distinguishes it from siblings by specifying it's 'the most surgical edit' that 'only modifies what you specify', contrasting with batch operations like batch_update_blocks or broader document edits like write_document.

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

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

The description provides clear context for when to use this tool ('only modifies what you specify' for 'surgical edit'), but doesn't explicitly state when not to use it or name specific alternatives. It implies this is for targeted updates versus batch operations, 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.

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

With no annotations provided, the description carries full burden and does well by disclosing critical behavioral traits: it replaces all content (destructive), syncs to UI in real-time, and warns about the replacement nature. It also hints at collaboration considerations but doesn't cover permissions, rate limits, or error handling in depth.

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

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

The description is appropriately sized and front-loaded with key information (replacement action and warning). Every sentence adds value, such as usage guidelines, XML details, and examples, though the structure could be slightly tighter by integrating examples more seamlessly.

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

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

Given the tool's complexity (destructive write operation with XML content and comments), no annotations, and no output schema, the description is largely complete: it covers purpose, usage, parameters, and behavioral aspects. However, it lacks details on error cases, response format, or authentication needs, leaving minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate fully. It adds substantial meaning beyond the schema: 'content' is TipTap XML with detailed block and mark examples, 'comments' is a dict mapping IDs to metadata with examples, and it implies 'graph_id' and 'document_id' identify the target. This effectively documents all parameters.

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

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

The description clearly states the specific action ('Replaces document content with TipTap XML') and resource ('document'), distinguishing it from sibling tools like 'append_to_document' by emphasizing replacement versus appending. It also mentions real-time UI syncing, adding operational context.

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

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

Explicit guidance is provided: use this tool to replace all content, and for collaborative editing, prefer 'append_to_document' instead. This directly addresses when to use this tool versus alternatives, with clear exclusions for specific scenarios.

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