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 key behaviors: automatic bullet-point formatting, link syntax requirements, inheritance of journal attributes, and format specifics for journalDay. It doesn't cover error conditions, permissions, or rate limits, but provides substantial operational context beyond basic functionality.

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 well-structured with clear sections: purpose statement, important notes with formatting rules, journal-specific behavior, and parameter explanations. Every sentence adds value, with no redundant information. The front-loaded purpose statement immediately communicates the tool's function.

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 no annotations and no output schema, the description provides substantial context about behavior, parameters, and Logseq-specific conventions. It covers the core functionality comprehensively but doesn't describe the return value structure (only mentions it returns 'information about the created block') or error conditions, which would be helpful given the lack of output schema.

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

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

With 0% schema description coverage, the description must compensate fully. It provides clear semantic explanations for all three parameters: page_name identifies the target page, content specifies the block text, and properties defines optional metadata. The description adds meaningful context about how these parameters interact with Logseq's behavior, though it could elaborate on properties format.

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 ('Creates a new block'), the resource ('on a page in the Logseq graph'), and distinguishes it from siblings like create_page (creates pages, not blocks) and insert_block (inserts blocks at specific positions). The verb+resource combination is specific and 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 about when to use this tool (creating blocks on pages, with formatting notes for links and journal pages). However, it doesn't explicitly state when NOT to use it or name alternatives like insert_block for positioning blocks at specific locations, which would be helpful for 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 effectively describes key behaviors: it explains what happens when creating journal pages (automatic property setting and formatting), which is valuable context beyond just the creation action. However, it doesn't mention potential errors, permissions needed, or rate limits, leaving some behavioral aspects uncovered.

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 well-structured and appropriately sized: it starts with the core purpose, provides specific usage guidelines, explains behavioral aspects for journal pages, and clearly documents parameters and returns. Every sentence adds value without redundancy, making it easy to parse and understand.

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 (creation tool with journal-specific behavior), no annotations, and no output schema, the description does a good job covering the essentials: purpose, usage, behavior, and parameters. However, it doesn't describe the return value format (beyond 'dict: Information about the created page'), which would be helpful since there's no output schema. For a creation tool, 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 must compensate for the lack of parameter documentation in the schema. It adds meaningful semantics: it explains that 'name' is for the new page and 'properties' are optional properties to set, and provides specific format guidance for journal page names. This goes beyond what the bare schema provides, though it could elaborate more on property structure.

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 the resource 'new page in the Logseq graph', distinguishing it from siblings like create_block (which creates blocks) or delete_page (which removes pages). It specifies the exact action and target resource 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 explicit guidance on when to use this tool vs. alternatives: it instructs to use the specific format 'mmm dth, yyyy' for journal pages and explains that journal pages are specially formatted with automatic dating. This helps differentiate from creating regular pages or using other tools like create_block for different content types.

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 does so effectively. It discloses critical behavioral traits: the operation is destructive ('removes the specified page and all its blocks'), irreversible ('cannot be undone'), and includes a special case for journal pages. This covers key aspects like destructiveness and constraints.

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 purpose, followed by behavioral details, usage guidelines, and parameter explanations. Every sentence adds value with no wasted words, making it efficient 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 the tool's complexity (destructive operation with 1 parameter) and no annotations or output schema, the description is largely complete. It covers purpose, behavior, usage, and parameters. A minor gap is the lack of detail on the return value ('dict: Result of the deletion operation') which is vague, but overall it provides sufficient context for safe 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?

The schema has 0% description coverage, so the description must compensate. It adds meaningful semantics by explaining that the 'name' parameter is 'the name of the page to delete' and provides a specific format example for journal pages ('mmm dth, yyyy'), which clarifies usage beyond the bare schema. This is strong compensation for 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 ('deletes'), the resource ('a page from the Logseq graph'), and distinguishes it from siblings like 'remove_block' or 'delete_page' by specifying it removes the page and all its blocks. This provides precise differentiation.

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

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

The description provides clear context for when to use this tool (to delete pages) and includes a specific guideline for journal pages with a format example. However, it does not explicitly mention when not to use it or name alternatives like 'remove_block' for partial deletions, which would have earned a 5.

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

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

With no annotations provided, the description carries full burden. It discloses the return format (list) and special attributes for journal pages, which is useful behavioral context. However, it doesn't mention performance implications (e.g., large graphs), pagination, error conditions, or authentication needs, leaving gaps for a read 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?

The description is appropriately sized with three sentences: purpose statement, journal page detail, and return format. It's front-loaded with the core function and avoids redundancy. The journal detail could be slightly more integrated, but overall it's efficient.

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 moderate complexity (retrieving all pages), the description provides the essential purpose and return type but lacks details on output structure (e.g., page fields), error handling, or performance considerations. It's minimally adequate but leaves the agent guessing about the full response format.

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

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

The tool has 0 parameters with 100% schema coverage, so the schema already fully documents the absence of inputs. The description appropriately doesn't add parameter information, maintaining focus on the tool's behavior and output. This meets the baseline for zero-parameter tools.

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 with a specific verb ('Gets') and resource ('all pages from the Logseq graph'). It distinguishes this tool from siblings like get_page (singular) and get_page_blocks, but doesn't explicitly contrast with search_blocks or other list-oriented 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 implies usage by mentioning journal page identification, suggesting this tool is for retrieving comprehensive page lists. However, it doesn't explicitly state when to use this vs. alternatives like search_blocks or get_page_blocks, nor does it provide exclusion criteria or prerequisites.

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 key behavioral traits: it describes the hierarchical structure information returned (parent, level, left), journal-specific fields, and the return format (dict). However, it doesn't mention error handling, permissions, or rate limits.

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 structured details about returned information, journal specifics, and parameter/return documentation. Every sentence adds value with zero 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 1 parameter with no schema descriptions, no annotations, and no output schema, the description does an excellent job covering purpose, behavior, and parameters. However, it doesn't fully address potential edge cases or error scenarios, leaving minor gaps in completeness.

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

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

With 0% schema description coverage for the single parameter, the description fully compensates by clearly explaining 'block_id (str): The ID of the block to retrieve.' This adds essential meaning beyond the bare schema, specifying the parameter's purpose and type.

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 ('Gets a specific block') and resource ('from the Logseq graph by its ID'), distinguishing it from siblings like get_page, get_page_blocks, or search_blocks. The verb 'gets' is precise and the scope is well-defined.

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 context by specifying retrieval by block ID, but doesn't explicitly state when to use this versus alternatives like get_page_blocks (which retrieves multiple blocks) or search_blocks (which finds blocks by content). It provides clear context but lacks explicit exclusions or named alternatives.

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 retrieves information (implied read-only) and specifies journal page attributes, but lacks details on error handling, permissions, rate limits, or what happens if the page doesn't exist. It adds some behavioral context but leaves gaps for a mutation-free 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 well-structured with a clear purpose statement, usage notes, and parameter/return sections. It is appropriately sized, but the journal attributes section could be more concise. Most sentences earn their place by providing essential information without 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?

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is largely complete. It covers purpose, parameter semantics, and return type. However, it lacks details on error cases or response structure, which would enhance completeness for a retrieval 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?

The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains the 'name' parameter in detail, including format requirements for journal pages ('mmm dth, yyyy') and examples, and clarifies that journal pages are automatically created. This fully compensates for the schema's lack of 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 ('Gets a specific page') and resource ('from the Logseq graph by name'), distinguishing it from siblings like get_all_pages (which lists all pages) and get_page_blocks (which focuses on page contents). The verb 'gets' 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.

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 (e.g., for journal pages, use specific date formats) and implies usage by specifying the target resource. However, it does not explicitly state when to choose alternatives like get_all_pages or get_page_blocks, nor does it mention prerequisites or 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 the full burden of behavioral disclosure. It effectively describes key behavioral traits: it specifies the hierarchical structure of returned blocks (parent, level, left), details special fields for journal pages (journal?, journalDay), and clarifies the return type (list of blocks). However, it doesn't mention potential errors (e.g., invalid page names) or performance aspects like pagination.

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 well-structured and appropriately sized: it starts with the core purpose, follows with usage guidelines and behavioral details, and ends with explicit Args and Returns sections. Every sentence adds value, though the formatting with bullet points and separate sections is slightly verbose but still efficient.

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 (retrieving structured data), no annotations, no output schema, and 1 parameter with 0% schema coverage, the description is largely complete. It covers purpose, usage, behavior, parameters, and return values. However, it lacks error handling information and doesn't explicitly state that it's a read-only operation (though implied by 'Gets').

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 fully compensate. It adds significant meaning beyond the bare schema: it explains the parameter 'page_name' as 'The name of the page to retrieve blocks from,' provides a specific format example for journal pages ('mmm dth, yyyy'), and implicitly clarifies that page names are strings. This fully documents the single parameter's semantics.

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

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

The description clearly states the specific action ('Gets all blocks') and resource ('from a specific page in the Logseq graph'), distinguishing it from siblings like get_block (single block), get_all_pages (pages only), and search_blocks (filtered search). The verb 'gets' is precise and the scope 'all blocks from a specific page' is well-defined.

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 explicitly provides when-to-use guidance: 'For journal pages, use the format "mmm dth, yyyy" (e.g., "Apr 4th, 2025").' This distinguishes usage from regular pages and offers a clear alternative format for a specific case, helping the agent choose correctly.

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. It discloses that the tool returns blocks with double bracket links, which is useful behavioral context. However, it lacks details on permissions, rate limits, error handling, or whether the operation is read-only (implied by 'Gets' but not explicit). More behavioral traits would improve this.

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 well-structured and front-loaded: the first sentence states the purpose, followed by details on link format and journal page handling, then clearly labeled Args and Returns sections. Every sentence adds value without redundancy, 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.

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 and no output schema, the description does a good job explaining inputs and outputs (list of blocks). It covers the tool's purpose and usage context adequately. However, for a tool with no annotations, it could benefit from more behavioral details like error cases or performance expectations to be fully complete.

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

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

Schema description coverage is 0%, so the description must compensate fully. It clearly explains the single parameter 'page_name', including its type (str) and purpose ('The name of the page to find references to'), and provides a specific format example for journal pages. This adds significant meaning 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 verb ('Gets') and resource ('all linked references to a specific page in the Logseq graph'), specifying the exact scope of what is retrieved. It distinguishes from siblings like get_page (which retrieves page content) or get_page_blocks (which retrieves blocks within a page) by focusing on cross-references.

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: to find blocks that link to a specific page. It explicitly mentions the format for journal pages, which is crucial guidance. However, it does not explicitly state when not to use it or name alternatives among siblings (e.g., search_blocks might also find references but differently).

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 important behavioral traits: automatic bullet point formatting, link syntax requirements, insertion position logic, and inheritance rules for journal pages. It doesn't cover error conditions or rate limits, but provides substantial operational 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 well-structured with clear sections (purpose, important notes, journal specifics, Args, Returns), front-loads the core functionality, and every sentence adds value. No redundant information or wasted words despite comprehensive coverage.

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 4-parameter mutation tool with no annotations and no output schema, the description provides excellent coverage of behavior, parameters, and usage context. The only gap is lack of explicit return value details beyond 'Information about the created block,' which would be helpful given no output schema.

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

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

With 0% schema description coverage, the description fully compensates by explaining all 4 parameters in detail: parent_block_id's role, content's purpose, properties as optional attributes, and before's positioning logic with default behavior. The Args section adds clear semantic meaning 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 ('inserts a new block as a child'), identifies the resource ('parent block'), and distinguishes from siblings like 'create_block' (which likely creates standalone blocks) and 'create_page' (which creates pages rather than blocks). The hierarchical content creation context further clarifies the purpose.

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 ('creating hierarchical content by adding children to existing blocks') and mentions journal page specifics. However, it doesn't explicitly state when NOT to use it or name alternatives like 'create_block' for non-hierarchical creation, 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 effectively describes key behavioral traits: the block maintains its children when moved, and the hierarchical outcome depends on the 'as_child' parameter (child vs. sibling placement). However, it does not cover aspects like permissions needed, error conditions, or rate limits, leaving some gaps in 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 appropriately sized and front-loaded, starting with a clear purpose statement, followed by elaboration, important notes, and structured parameter details. Every sentence adds value without redundancy, such as explaining hierarchical dependencies and parameter defaults, making it efficient and well-organized for agent 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 the tool's moderate complexity (3 parameters, no annotations, no output schema), the description is largely complete. It covers purpose, behavioral traits, and parameter semantics effectively. However, it lacks details on the return value (only states 'dict: Result of the move operation' without specifics) and does not address potential errors or side effects, leaving minor gaps in 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?

The schema description coverage is 0%, so the description must compensate fully. It adds significant meaning beyond the bare schema by explaining each parameter: block_id as 'the ID of the block to move', target_block_id as 'the ID of the target block to move to', and as_child with detailed semantics on child vs. sibling placement and default behavior. This provides clear context that the schema alone lacks.

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 ('Moves a block to a new location') and resource ('in the graph'), distinguishing it from siblings like create_block, insert_block, or remove_block by focusing on relocation rather than creation, insertion, or deletion. The second sentence elaborates on the purpose of reorganizing block structure, reinforcing the distinct functionality.

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 reorganizing block structure but does not explicitly state when to use this tool versus alternatives like insert_block or update_block. It provides context about moving blocks with children, which hints at usage scenarios, but lacks clear guidance on prerequisites, exclusions, or named alternatives for different use cases.

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 clearly states critical behavioral traits: the operation is permanent, removes children recursively, cannot be undone, and requires specific permissions/access (block ID from other functions). This goes well beyond basic parameter documentation.

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 structured: purpose statement first, critical behavioral warnings next, usage prerequisites, then parameter and return documentation. Every sentence earns its place with essential information, and there's no 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?

For a destructive operation with no annotations and no output schema, the description provides excellent completeness. It covers purpose, behavioral consequences (permanent, recursive), prerequisites, parameter meaning, and return type. Given the tool's complexity and lack of structured metadata, this is comprehensive.

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 has 0% description coverage, so the description must compensate. It explains what block_id represents, how to obtain it (listing three specific functions), and its purpose in the removal operation. This adds substantial meaning beyond the bare schema, though it doesn't detail format constraints.

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 ('removes a block') and resource ('from the Logseq graph'), distinguishing it from siblings like delete_page (which removes pages) or update_block (which modifies blocks). The verb 'removes' 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.

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 by specifying prerequisites (needing a block ID) and listing three sibling tools that can provide that ID. However, it doesn't explicitly state when NOT to use it or compare it to alternatives like delete_page for page-level removal.

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 returned blocks from journal pages include specific metadata fields ('journal?' and 'journalDay'), which is valuable behavioral context. However, it doesn't mention pagination, rate limits, permission requirements, or what happens with empty/no results.

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: purpose statement first, followed by categorized examples, then parameter documentation. Every sentence adds value - the examples are particularly helpful for understanding query capabilities without being verbose.

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

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

For a single-parameter search tool with no annotations or output schema, the description provides good coverage of purpose, parameter usage, and some behavioral details. The main gap is lack of output format details beyond mentioning journal fields - no information about block structure, error cases, or result limitations.

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 (schema only has title 'Query'), the description fully compensates by explaining the query parameter with multiple concrete examples and syntax patterns. It transforms a generic 'string' parameter into a meaningful search syntax with specific use cases.

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 with a specific verb ('searches for blocks') and resource ('in the Logseq graph'), distinguishing it from siblings like get_block (retrieves single block) or get_page_blocks (gets all blocks from a page). It provides concrete examples of what 'blocks matching a query' means.

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 through query examples (page-specific, term-based, journal, references), giving implicit guidance on when to use this tool. However, it doesn't explicitly state when to use alternatives like get_page_blocks for all blocks on a page without filtering, or get_page_linked_references for specific reference types.

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 important behavioral traits: automatic bullet formatting, link syntax using double brackets, and preservation of journal attributes. However, it doesn't mention permissions needed, error conditions, or whether the update is reversible/destructive.

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

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

Well-structured with purpose statement, important notes section, and parameter/return documentation. Every sentence adds value, though the journal-specific section could be slightly more integrated. Front-loading the core purpose is effective.

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, and no output schema, the description does reasonably well by explaining parameters and some behaviors. However, it lacks details on return value structure, error handling, and complete behavioral context, leaving gaps for the 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?

Schema description coverage is 0%, so the description must compensate. It provides meaningful explanations for all 3 parameters: block_id identifies the target, content is the new text, and properties are optional metadata. This adds significant value beyond the bare schema, though format details for properties could be more specific.

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 ('Updates') and resource ('an existing block in the Logseq graph'), distinguishing it from siblings like create_block (creates new) or remove_block (deletes). It specifies it's for existing blocks only, not creation.

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 (updating existing blocks) and implies alternatives through sibling tool names (e.g., create_block for new blocks, get_block for reading). However, it doesn't explicitly state when NOT to use it or compare directly to alternatives like insert_block.

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