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 automatic bullet formatting and link syntax, which are useful behavioral details, but fails to address critical aspects like permissions required, whether creation is idempotent, error conditions, or what 'Information about the created block' entails. For a mutation tool with zero annotation coverage, this 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 well-structured with purpose statement, behavioral note, parameter documentation, and return indication. Each section earns its place, though the 'Returns' statement is vague. The text is appropriately sized for a 3-parameter tool without 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?

Given a mutation tool with 3 parameters, no annotations, and no output schema, the description is moderately complete. It covers parameter semantics well and includes some behavioral context (formatting, linking), but lacks details about the return value, error handling, and operational constraints. The absence of output schema means the vague 'Information about the created block' leaves the agent uncertain about response structure.

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 explicitly documents all three parameters with clear semantics: 'page_name: The name of the page to create the block on', 'content: The content of the new block', and 'properties: Optional properties to set on the new block'. With 0% schema description coverage, this fully compensates by providing meaning beyond the bare schema types. The optional nature of 'properties' is correctly indicated.

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 specific verb ('creates') and resource ('new block on a page in the Logseq graph'), and distinguishes it from siblings like 'create_page' by specifying it creates blocks rather than pages. The mention of 'automatically formatted as bullet points' further clarifies the nature of the created resource.

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 implied usage guidance through the note about formatting and link syntax ('Use [[Page Name]] to create links'), but lacks explicit when-to-use guidance versus alternatives like 'insert_block' or 'update_block'. No exclusions or prerequisites are mentioned, leaving the agent to infer appropriate contexts.

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 Logseq automatically sets journal properties, which is useful behavioral context. However, it doesn't mention permissions needed, error conditions, or whether the operation is idempotent. For a creation tool with zero annotation coverage, this leaves gaps in behavioral understanding.

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 with the core purpose. Each sentence adds value: the first states the action, the second provides journal-specific formatting, the third explains automatic behavior, and the last two clarify parameters and returns. 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 no annotations and no output schema, the description does a good job covering the basics: purpose, journal formatting, parameters, and return info. However, for a creation tool, it could better explain error handling or what 'Information about the created page' includes. It's mostly complete but has 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. It explains that 'name' is 'The name of the new page' and 'properties' are 'Optional properties to set on the new page', adding meaningful semantics beyond the bare schema. However, it doesn't detail what properties are valid or provide examples beyond journal formatting.

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 ('Creates a new page') and resource ('in the Logseq graph'), distinguishing it from siblings like create_block (which creates blocks) or delete_page (which removes pages). The verb+resource combination 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 explicit guidance on when to use this tool vs alternatives: it specifies 'For journal pages, use the format "mmm dth, yyyy"' and notes that Logseq automatically handles journal-specific properties. This gives clear context for journal page creation versus regular pages.

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 communicates critical behavioral traits: that the operation is destructive ('removes the page and all its blocks'), irreversible ('Cannot be undone'), and returns a result. This covers the essential safety and outcome information needed for a destructive 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 efficiently structured with a clear purpose statement, critical warning, and organized parameter/return sections. Every sentence serves a distinct purpose: establishing action, warning about consequences, explaining the parameter, and describing the return value. 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?

For a destructive tool with no annotations and no output schema, the description provides strong coverage of purpose, behavior, and parameter meaning. The main gap is the lack of detail about what the 'Result of the deletion operation' actually contains, which would be helpful given the absence of an 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 for the single parameter, the description compensates by explaining that 'name' refers to 'The name of the page to delete.' This adds meaningful context beyond the bare schema, clarifying what the parameter represents in the tool's domain.

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') and target resource ('a page from the Logseq graph'), distinguishing it from sibling tools like remove_block or create_page. It precisely communicates what the tool does without being vague or tautological.

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 (to delete a page and all its blocks) and includes a warning about irreversibility, which helps guide usage decisions. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools for partial deletions.

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 what the tool returns but lacks critical details: whether it's paginated for large graphs, if it requires specific permissions, potential rate limits, or error conditions. The journal attribute detail is useful but doesn't cover core behavioral traits like performance or access control.

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 concise: it opens with the core purpose, adds a clarifying detail about journal pages, and ends with the return value. Each sentence earns its place, and there's no fluff. However, it could be slightly more front-loaded by merging the first and last sentences for immediate clarity.

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 simplicity (0 parameters, no annotations, no output schema), the description is minimally adequate. It explains what 'pages' are and hints at structure via journal attributes, but lacks output format details (e.g., list structure, fields per page) and behavioral context. For a read-only list operation, this is passable but leaves gaps an agent might need.

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, and schema description coverage is 100% (empty schema). The description appropriately doesn't discuss parameters, focusing instead on output semantics (journal page attributes). This meets the baseline of 4 for zero-parameter tools, as it adds value by explaining what 'pages' include without redundant parameter info.

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 pages from the Logseq graph'), making the purpose unambiguous. It distinguishes itself from siblings like get_page (single page) and get_page_blocks (blocks within a page) by specifying 'all pages'. However, it doesn't explicitly contrast with search_blocks or get_page_linked_references, which serve different but related purposes.

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, performance considerations for large graphs, or when to prefer get_page (for a specific page) or search_blocks (for filtered content). The journal page detail is informational but not a usage guideline.

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

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 hierarchical structure information (parent, level, left) and handles missing blocks by returning None, which adds useful behavioral context beyond just being a read operation. However, it doesn't mention error conditions, performance characteristics, or authentication needs.

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 with a clear purpose statement, bullet points for return details, and labeled Args/Returns sections. Every sentence adds value with no 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?

For a simple read operation with 1 parameter and no output schema, the description is reasonably complete: it explains what the tool does, what parameter it needs, what information it returns, and the not-found case. The main gap is lack of explicit usage guidance versus sibling tools.

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 and only 1 parameter, the description compensates well by explaining that 'block_id' is 'The ID of the block to retrieve,' providing clear semantic meaning. It doesn't specify format or constraints, but for a single parameter tool this is adequate.

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 which operate on different resources or with different scopes.

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 specifying it retrieves a block by ID, but doesn't explicitly state when to use this versus alternatives like get_page_blocks (for all blocks on a page) or search_blocks (for query-based retrieval). 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 of behavioral disclosure. It explains that the tool returns page information or None if not found, which is useful. However, it lacks details on permissions, error handling, rate limits, or whether this is a read-only operation, which are important for a tool interacting with a graph system.

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 guidelines, and labeled sections for Args and Returns. It is appropriately sized, but the journal page details could be slightly more concise, and the front-loading is effective with the main action stated 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 the complexity of interacting with a graph system, no annotations, and no output schema, the description is moderately complete. It covers the purpose, parameter semantics, and basic return behavior, but lacks details on output structure, error cases, or integration with sibling tools, leaving room for improvement.

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 meaningful context for the 'name' parameter, explaining the specific format for journal pages and their attributes, which goes beyond the basic schema. However, it does not cover other potential nuances like case sensitivity or special characters for non-journal pages.

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 retrieves blocks within a page). 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 provides explicit guidance on when to use this tool for journal pages, specifying the required date format ('mmm dth, yyyy') and attributes. However, it does not mention when NOT to use it or explicitly compare it to alternatives like get_all_pages or get_page_blocks, leaving some context gaps.

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 adds valuable context beyond the basic purpose: it specifies the hierarchical structure information returned (parent, level, left), which helps the agent understand the output format. However, it doesn't mention potential errors (e.g., if the page doesn't exist), rate limits, or authentication needs, leaving some gaps. This earns a 4 for adding significant behavioral details but not being exhaustive.

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

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

The description is appropriately sized and well-structured: it starts with the core purpose, provides usage guidelines, details the return structure, and lists parameters clearly with 'Args' and 'Returns' sections. Every sentence adds value without redundancy, making it easy to scan and understand quickly.

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 low schema coverage, the description does a good job of being complete. It explains the purpose, parameter usage, and return format in detail. However, it lacks information on error handling or performance aspects (e.g., pagination for large pages), which prevents a perfect score. Overall, it's largely sufficient for an agent to use the tool effectively.

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 beyond the input schema by explaining the 'page_name' parameter: 'The name of the page to retrieve blocks from.' and provides a specific format example for journal pages. This clarifies the parameter's purpose and usage, effectively compensating for the lack of schema descriptions. However, it doesn't cover edge cases or validation rules, so it's not a perfect 5.

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: 'Gets all blocks from a specific page in the Logseq graph.' It specifies the verb ('Gets'), resource ('blocks'), and scope ('from a specific page'), which is specific and actionable. However, it doesn't explicitly differentiate from sibling tools like 'get_block' or 'search_blocks', which limits the score to 4 instead of 5.

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

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

The description provides some usage guidance: 'For journal pages, use the format "mmm dth, yyyy" (e.g., "Apr 4th, 2025").' This implies context for when to use a specific format, but it doesn't explicitly state when to use this tool versus alternatives like 'get_block' (for single blocks) or 'search_blocks' (for filtered searches). The guidance is helpful but incomplete, warranting a score of 3.

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 describes what the tool does (gets references) and the return format (list of blocks), but lacks behavioral details such as whether it requires authentication, how it handles non-existent pages, pagination, rate limits, or error conditions. The description doesn't 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, the second clarifies the return content, and the Args/Returns sections are concise and necessary. Every sentence earns its place with no 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 moderate complexity (finding references), no annotations, no output schema, and 1 parameter, the description is somewhat complete but has gaps. It explains the purpose, parameter, and return type, but lacks behavioral context (e.g., error handling, performance). The absence of an output schema means the description should ideally detail the return structure more, though it does specify 'List of blocks.'

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 schema has no descriptions for parameters), the description compensates by explaining the single parameter 'page_name' as 'The name of the page to find references to.' This adds clear meaning beyond the bare schema. However, it doesn't specify format constraints (e.g., case sensitivity, special characters).

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 specific verb ('Gets') and resource ('all linked references to a specific page'), and distinguishes it from siblings like get_page (which retrieves page content) and get_page_blocks (which retrieves blocks within a page). The second sentence further clarifies what constitutes a 'linked reference' by mentioning 'blocks containing [[Page Name]] links'.

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 implicitly indicates when to use this tool (to find references to a specific page) but does not explicitly state when not to use it or name alternatives. For example, it doesn't clarify if this should be used instead of search_blocks for finding references, though the context suggests this is the specialized tool for that purpose.

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 key behavioral traits: the tool creates new content (mutation operation), specifies insertion position logic (beginning vs end), and mentions hierarchical relationships. However, it doesn't cover permissions needed, error conditions, 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?

Perfectly structured with purpose statement, usage context, parameter explanations, and return value note. Every sentence earns its place: first states core function, second explains hierarchical context, third details insertion logic, Args section documents parameters efficiently, Returns section sets expectations.

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 good coverage: clear purpose, usage context, parameter semantics, and behavioral aspects like insertion position. The main gap is lack of output details (only mentions 'Information about the created block' without specifics).

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 4 parameters in the Args section. It clarifies parent_block_id's role, content's purpose, properties as optional settings, and before's positional logic with default behavior. This adds substantial 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') and resource ('as a child of the specified parent block'), distinguishing it from sibling tools like create_block (which likely creates standalone blocks) and move_block (which repositions existing blocks). The hierarchical nature is explicitly mentioned.

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 ('Creates hierarchical content by adding children to existing blocks'), but doesn't explicitly mention when not to use it or name specific alternatives. It implies usage for adding child blocks to existing parents rather than creating standalone 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 full burden but lacks critical behavioral details. It mentions moving 'all its children' and the as_child parameter effects, but doesn't disclose permissions needed, whether the operation is reversible, error conditions, or what 'Result of the move operation' entails. For a mutation tool with zero annotation coverage, this is insufficient.

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, elaboration, parameter details, and return mention. The bullet points for as_child values are efficient. Slightly verbose in repeating 'block' in parameter explanations, but overall earns its place without 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 mutation tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It explains parameters well but misses behavioral context (permissions, side effects, error handling) and output details. Should provide more guidance given the complexity.

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

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

Schema description coverage is 0%, so the description must compensate fully. It provides clear semantic explanations for all three parameters: block_id identifies what to move, target_block_id specifies where, and as_child defines the relationship with detailed boolean interpretations. This 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 ('moves a block to a new location') and resource ('block and all its children'), distinguishing it from siblings like insert_block (adds new) or remove_block (deletes). The second sentence elaborates on scope, 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?

Usage is implied through parameter explanations (as_child=True/False scenarios), but there's no explicit guidance on when to use this tool versus alternatives like insert_block or update_block for structural changes. The description doesn't 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 full burden and excels. It discloses critical behavioral traits: the operation is permanent ('Cannot be undone'), destructive ('Permanently removes'), and cascading ('and all its children'). This goes well beyond what a basic 'remove' verb would imply, providing essential safety 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 perfectly structured and front-loaded: purpose statement first, critical warning second, then parameter and return documentation. Every sentence earns its place - the warning is essential safety information, and the Args/Returns sections provide necessary documentation without 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 mutation tool with no annotations and no output schema, the description does an excellent job covering safety implications and parameter meaning. The main gap is the vague return description ('Result of the removal operation') - more specificity about success/failure indicators would have made this a 5, but overall it's highly complete given the 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 (the schema only shows block_id as a string with no description), the description compensates by explaining what block_id represents ('The ID of the block to remove'). This adds meaningful context beyond the bare schema. It doesn't provide format examples or validation rules, so it's not a perfect 5.

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') and target resource ('a block from the Logseq graph'), distinguishing it from siblings like delete_page (which removes pages) and update_block (which modifies blocks). The verb+resource combination 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 about when to use this tool (to permanently remove blocks) through the warning about permanent deletion. However, it doesn't explicitly mention when NOT to use it or name specific alternatives like delete_page for removing pages instead of blocks, 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 the full burden of behavioral disclosure. It adequately describes the core behavior (searching for blocks matching a query) and provides helpful query syntax examples, but doesn't address important behavioral aspects like whether results are paginated, sorted, or limited; what happens with no matches; or any performance considerations. The description adds value but leaves gaps 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 perfectly structured and economical. It begins with the core purpose statement, follows with practical query examples in a bulleted format, then clearly documents the single parameter and return value. Every sentence earns its place, with no redundant or unnecessary information. The formatting with clear sections enhances readability.

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 and no output schema, the description provides excellent coverage of the core functionality, parameter usage, and return type. The query examples are particularly valuable. The main gap is the lack of information about the return format - while it states 'List of blocks matching the search query,' it doesn't specify what fields blocks contain or their structure. Given the tool's relative simplicity, this is a minor omission.

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

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

With 0% schema description coverage for the single parameter, the description fully compensates by providing rich semantic information about the 'query' parameter. It not only explains what the parameter is ('The search query') but provides three concrete examples with different syntax patterns, giving the agent practical guidance on how to construct effective queries. This goes well beyond what the bare schema provides.

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

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

The description clearly states the specific action ('searches for blocks matching a query') and resource ('in the Logseq graph'), distinguishing it from sibling tools like get_block, get_page_blocks, or get_page_linked_references which retrieve specific blocks or pages without search functionality. The verb+resource combination 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 through query examples that demonstrate different search scenarios, such as finding blocks on a specific page or containing a term. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the examples imply it's for flexible searching rather than direct retrieval.

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 an update operation and mentions link creation syntax, it doesn't describe important behavioral aspects like permission requirements, whether the update overwrites or merges content, error conditions, or what 'Information about the updated block' actually contains. Significant gaps remain 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 well-structured with clear sections (purpose, usage tip, args, returns) and reasonably concise. The 'Use [[Page Name]]...' tip is helpful but could be more integrated. Overall efficient with minimal 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?

For a mutation tool with 3 parameters, 0% schema description coverage, and no output schema, the description provides basic parameter semantics and return indication but lacks details on behavioral aspects, error handling, and the actual return format. It's minimally adequate but has clear gaps given the complexity.

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

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

The description provides clear parameter explanations beyond the schema (which has 0% description coverage): it defines block_id as 'The ID of the block to update', content as 'The new content for the block', and properties as 'Optional properties to update on the block'. This adds substantial value over the bare schema, 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 verb 'Updates' and resource 'existing block in the Logseq graph', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'insert_block' or 'move_block' beyond the basic operation name.

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 implied usage context by mentioning 'Use [[Page Name]] to create links to other pages' and listing parameters, but doesn't explicitly state when to use this tool versus alternatives like 'insert_block' or 'move_block'. No clear when-not-to-use guidance or prerequisites are provided.

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