Roam Research
Server Quality Checklist
This repository includes a README.md file.
This repository includes a LICENSE file.
Latest release: v2.13.0
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
- This server provides 22 tools. View schema
No known security issues or vulnerabilities reported.
Are you the author?
Add related servers to improve discoverability.
Tool Scores
- Behavior2/5
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 but offers minimal information. It mentions 'returns content in the specified format' but doesn't describe error handling (e.g., what happens if the title doesn't exist), rate limits, authentication requirements, or side effects. The input schema hints at multi-graph and write_key complexities, but the description doesn't explain these behavioral aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose in the first sentence. The second sentence adds useful context about return formats. There's no wasted text, though it could be more structured with bullet points for clarity. Overall, it's efficiently written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema, no annotations), the description is insufficient. It doesn't explain the return structure, error cases, or how parameters like 'graph' and 'write_key' affect behavior in multi-graph scenarios. For a fetch operation with potential configuration nuances, more context is needed to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds no additional meaning beyond the schema's details for 'title' and 'format'. It doesn't clarify parameter interactions or provide examples, so it meets the baseline score of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetch' and resource 'page by title', making the purpose understandable. It distinguishes from siblings like 'roam_search_by_text' or 'roam_search_by_date' by focusing on exact title matching rather than search. However, it doesn't explicitly contrast with 'roam_fetch_block_with_children' or 'roam_recall', which might have overlapping retrieval functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description doesn't mention when to choose this over 'roam_search_by_text' for title-based queries or 'roam_fetch_block_with_children' for block retrieval. It also lacks prerequisites like authentication needs or graph configuration, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves and returns a deduplicated list, which is useful, but lacks details on permissions, rate limits, error handling, or what constitutes a 'memory' (e.g., format, size limits). For a retrieval tool with zero annotation coverage, this leaves significant gaps in understanding its operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the core purpose in the first sentence. It uses two sentences total, with the second covering optional features (filtering and sorting). There's no wasted text, though a minor typo ('blcoks') slightly detracts from clarity. Overall, it's efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain the return format (e.g., structure of memories list), error conditions, or dependencies like when graph or write_key are required. For a tool with multiple optional parameters and no output schema, more context is needed to ensure proper usage without trial and error.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema: it mentions optional filtering by tag and sorting by creation date, but these are already covered in the schema descriptions for filter_tag and sort_by. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Retrieve all stored memories on page titled ROAM_MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories.' It specifies the verb (retrieve), resource (memories), and scope (page or tagged blocks). However, it doesn't explicitly differentiate from sibling tools like roam_search_for_tag or roam_search_by_text, which also retrieve content based on tags or text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 mentions optional filtering and sorting but doesn't compare it to sibling tools like roam_search_for_tag (for tag-based searches) or roam_search_by_date (for date-based retrieval). There's no mention of prerequisites, such as when the graph or write_key parameters are needed, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'pagination and sorting options' but doesn't detail performance implications, error conditions, or what happens with large datasets. For a query tool with 5 parameters, this leaves significant gaps in understanding how the tool behaves 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose ('Find pages that have been modified today') and efficiently notes additional features ('with pagination and sorting options'). Every word earns its place, making it concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavioral traits, usage context, and output format. Without annotations or an output schema, the agent must rely heavily on the schema for parameter details, leaving gaps in overall understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't explain how 'graph' or 'write_key' relate to the query). With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find pages that have been modified today (since midnight)'. It specifies the resource (pages) and the action (find) with a time constraint. However, it doesn't explicitly differentiate from sibling tools like 'roam_search_by_date' or 'roam_search_by_text', which might offer similar functionality with different filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 mentions pagination and sorting options but doesn't specify scenarios where this tool is preferred over siblings like 'roam_search_by_date' or 'roam_search_by_text', leaving the agent to infer usage based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It mentions searching but doesn't disclose if this is a read-only operation, potential rate limits, authentication needs (implied by write_key parameter but not explained), or what happens with invalid inputs. The description adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and key capability (searching up or down). There is zero waste, making it easy for an agent to quickly grasp the tool's function without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain return values, error conditions, or behavioral traits like mutability or side effects. For a search tool with multiple optional parameters and no structured safety hints, more context is needed to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no additional meaning about parameters, such as clarifying the relationship between parent_uid and child_uid or how max_depth interacts with search direction. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for parent or child blocks in the block hierarchy, specifying direction (up or down) from a given block. It distinguishes from siblings like roam_search_by_text or roam_search_for_tag by focusing on hierarchical relationships rather than content-based searches. However, it doesn't explicitly differentiate from roam_fetch_block_with_children, which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating it searches 'from a given block' and can go 'up or down the hierarchy,' suggesting when to use it versus content-based search tools. However, it doesn't explicitly state when not to use it or name alternatives among siblings, such as roam_fetch_block_with_children for child retrieval, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool 'provides content' and optional concatenation, but doesn't disclose behavioral traits like whether this is a read-only operation (implied but not stated), whether it requires authentication, rate limits, what format the content is returned in, or if there are any side effects. For a tool with no 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and includes the optional feature. Every word earns its place with zero redundancy or unnecessary elaboration. It's appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's apparent simplicity (retrieving a cheatsheet) and 100% schema coverage, the description is somewhat complete but has gaps. No output schema exists, so the description doesn't explain what 'content' means (e.g., markdown text, HTML, structured data). With no annotations, it also misses behavioral context like safety or performance characteristics. For a retrieval tool, this is minimally adequate but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (graph and write_key) with clear descriptions. The description doesn't add any parameter-specific information beyond what's in the schema, nor does it explain how parameters relate to the cheatsheet retrieval. With high schema coverage, the baseline is 3 even without param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Provides the content of the Roam Markdown Cheatsheet resource' - a specific verb ('provides') and resource ('Roam Markdown Cheatsheet resource'). It distinguishes itself from siblings like roam_create_page or roam_update_page_markdown by being a retrieval tool rather than a creation/modification tool. However, it doesn't explicitly contrast with other retrieval tools like roam_fetch_page_by_title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'optionally concatenated with custom instructions if CUSTOM_INSTRUCTIONS_PATH is set,' suggesting this tool is for accessing a predefined cheatsheet with optional customization. However, it doesn't explicitly state when to use this versus alternatives like roam_search_by_text for general markdown queries or when the cheatsheet would be more appropriate than other resources. No explicit 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.
- Behavior2/5
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 describes the search functionality, it doesn't mention important behavioral aspects like whether this is a read-only operation (likely, but not stated), performance characteristics, rate limits, authentication requirements for multi-graph operations, or what the output format looks like. The description is functional but lacks 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in a single sentence that clearly states the purpose and scope. It's front-loaded with the core functionality and avoids unnecessary elaboration. While very concise, it could potentially benefit from slightly more operational context given the lack of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (search results format), doesn't mention authentication requirements for the write_key parameter, and provides minimal guidance on when to use which search approach. For a tool with this level of complexity and zero annotation coverage, more comprehensive description is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description adds some context about searching 'within a page or across the entire graph' which relates to the page_title_uid parameter, but doesn't provide additional semantic meaning beyond what's already in the parameter descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search for block references'), resource ('within a page or across the entire graph'), and scope ('to a specific block, a page title, or find all block references'). It distinguishes itself from sibling tools like roam_search_by_text or roam_search_for_tag by focusing specifically on block references rather than general text or tag searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'within a page or across the entire graph' and different search targets, but doesn't explicitly state when to use this tool versus alternatives like roam_search_by_text for general text searches or roam_search_for_tag for tag-based searches. No explicit exclusions 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.
- Behavior3/5
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 useful context: it explains how the memory is stored (on the daily page with a tag), mentions tag handling rules, and notes a prerequisite resource. However, it doesn't disclose critical behavioral traits like whether this is a write operation (implied by 'Add'), potential side effects, error conditions, or rate limits. The description doesn't contradict annotations (none exist), but it leaves 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise but could be better structured. The first sentence clearly states the purpose, but the following notes on Roam markdown syntax and the prerequisite instruction, while useful, are lengthy and might be better placed elsewhere. The description isn't fully front-loaded, as the critical usage information is interspersed with formatting details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, mutation operation) and the absence of both annotations and an output schema, the description is partially complete. It covers the basic purpose, some usage context, and formatting rules, but lacks details on behavioral traits (e.g., what happens on failure, response format) and doesn't fully compensate for the missing structured data. For a write tool with no output schema, more behavioral disclosure would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal parameter semantics beyond the schema: it briefly mentions the categories parameter ('optional categories') and include_memories_tag ('unless include_memories_tag is false'), but doesn't provide additional meaning or examples for parameters like memory, heading, or parent_uid. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add a memory or piece of information to remember, stored on the daily page with ROAM_MEMORIES_TAG tag and optional categories.' This specifies the verb ('Add'), resource ('memory'), and destination ('daily page'). However, it doesn't explicitly differentiate this from sibling tools like roam_recall (which likely retrieves memories) or roam_add_todo (which adds tasks rather than memories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: it specifies that memories are stored on the daily page with a specific tag, mentions optional categories, and includes an important prerequisite ('ensure that you have loaded into context the "Roam Markdown Cheatsheet" resource'). However, it doesn't explicitly state when NOT to use this tool or name alternatives among siblings (e.g., when to use roam_add_todo vs. roam_remember).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions searching but does not disclose behavioral traits such as whether this is a read-only operation, what permissions are needed, how results are returned (e.g., pagination, format), or any rate limits. The description is minimal and lacks critical 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part of the sentence contributes directly to understanding the tool's function, 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.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no annotations, no output schema), the description is incomplete. It does not explain return values, error conditions, or behavioral aspects like authentication needs or result limitations. For a search tool with multiple parameters and no structured output, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description mentions 'specific status (TODO/DONE)' and 'across all pages or within a specific page', which aligns with the schema but adds no significant meaning beyond it. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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'), target resource ('blocks with a specific status'), and scope ('across all pages or within a specific page'). It distinguishes from siblings like roam_search_by_text or roam_search_by_date by focusing on status-based filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage ('across all pages or within a specific page'), but does not explicitly state when to use this tool versus alternatives like roam_search_by_text or roam_search_for_tag. It implies usage for status-based searches 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.
- Behavior3/5
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 pagination support and the specific use case for ROAM_MEMORIES_TAG, which adds useful context. However, it doesn't describe performance characteristics, error conditions, or what the return format looks like (especially important since there's no output schema), leaving 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with three sentences. The first sentence states the core purpose, the second mentions key parameters, and the third provides usage guidance. However, the second sentence could be more front-loaded by starting with the primary purpose rather than parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 8 parameters, 100% schema coverage, but no output schema and no annotations, the description is adequate but has clear gaps. It explains the core purpose and provides a specific use case, but doesn't describe the return format or what constitutes a 'block' in the results. Given the complexity and lack of output schema, more completeness would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all parameters are well-documented in the schema itself. The description adds minimal value beyond the schema - it mentions 'primary_tag' and 'page_title_uid' by name but doesn't provide additional semantic context. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for blocks containing a specific tag.' It specifies the resource (blocks) and action (search) with the target (tag). However, it doesn't explicitly differentiate from sibling tools like 'roam_search_by_text' or 'roam_search_block_refs', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Use this tool to search for memories tagged with the ROAM_MEMORIES_TAG.' This gives a specific use case, but it doesn't explicitly state when to use alternatives like 'roam_search_by_text' for non-tag searches or 'roam_search_block_refs' for block references, which would be needed for a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the return structure ('nested object structure containing the block's UID, text, order, and an array of its children'), which is valuable behavioral context. However, it doesn't mention potential errors (e.g., invalid UID), performance implications of depth, or authentication needs for the write_key parameter, leaving 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose, key feature (children inclusion), and return format without any redundant information. It's front-loaded with the core action and resource, making it highly concise and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 provides basic completeness by explaining the return structure. However, for a tool with 4 parameters (including optional ones like write_key that hint at multi-graph complexities) and no safety annotations, it lacks details on error handling, permissions, or example outputs, leaving room for improvement in contextual coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain the hierarchical implications of 'depth' or clarify 'graph' usage further). Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch a block by its UID'), the resource ('block'), and distinguishes it from siblings by specifying it includes hierarchical children down to a specified depth. This differentiates it from other fetch/search tools like roam_fetch_page_by_title or roam_search_hierarchy that don't mention this child-inclusion feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'hierarchical children down to a specified depth,' suggesting this tool is for retrieving nested block structures rather than flat results. However, it doesn't explicitly state when to use this versus alternatives like roam_search_hierarchy or roam_fetch_page_by_title, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the action ('Rename') which implies mutation, but doesn't disclose behavioral traits such as permission requirements, whether the rename affects linked references, error handling, or confirmation needs beyond the write_key parameter. For a mutation tool with zero annotation coverage, this is a significant gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('Rename a page') and adds necessary context ('by changing its title. Identifies the page by current title or UID.'). Every word earns its place with zero waste, 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.
Completeness3/5Given 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 5 parameters and no annotations or output schema, the description is adequate but incomplete. It covers the basic purpose and identification method, but lacks details on behavioral aspects like permissions, effects on references, or return values. It meets minimum viability but has clear gaps for a tool that modifies data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value by implying the identification method (title or UID), but doesn't provide additional syntax, format details, or usage nuances beyond what the schema specifies. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Rename') and resource ('a page'), specifying the action is to change its title. It distinguishes from siblings like roam_create_page (creation) and roam_update_page_markdown (content update), making the purpose specific and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining how to identify the page (by current title or UID), but it doesn't explicitly state when to use this tool versus alternatives like roam_create_page for new pages or roam_update_page_markdown for content changes. It offers identification guidance but lacks explicit sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by mentioning pagination behavior and performance implications ('very large results sets can impact performance'), but doesn't cover important aspects like authentication requirements (write_key parameter's purpose is unclear), rate limits, error conditions, or what the return format looks like. The description adds useful context but 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences that each serve a purpose: stating the core functionality, explaining scope usage, and mentioning pagination support. It's front-loaded with the main purpose and avoids unnecessary elaboration. One minor improvement could be more explicit differentiation from sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 8 parameters, no annotations, and no output schema, the description provides adequate but incomplete coverage. It explains the core search functionality and scope options well, but doesn't address the return format, error handling, or clarify the purpose of parameters like 'graph' and 'write_key' which appear to relate to multi-graph configurations and authentication. The description is functional but leaves the agent guessing about important operational aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all 8 parameters thoroughly. The description adds minimal value beyond the schema - it mentions the scope parameter's namespace prefix usage and pagination support, but doesn't provide additional semantic context about parameter interactions or edge cases. The baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for blocks containing specific text across all pages or within a specific page, with a specific verb ('search') and resource ('blocks'/'pages'). It distinguishes itself from siblings like roam_search_by_date, roam_search_for_tag, and roam_search_block_refs by focusing on text content search rather than date, tag, or reference-based searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use different scopes ('blocks' vs 'page_titles') and mentions pagination usage. However, it doesn't explicitly state when to choose this tool over alternatives like roam_search_block_refs or roam_search_for_tag, nor does it provide exclusion criteria for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a search/read operation (not destructive) and specifies the exclusion for daily pages, which is useful context. However, it doesn't describe important behavioral aspects like pagination, rate limits, authentication requirements, or what the response format looks like (especially since there's no output schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with just two sentences that each earn their place. The first sentence states the core purpose, and the second provides important exclusion guidance. No wasted words, and the most critical information (what it does) comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 7 parameters, 100% schema coverage, but no annotations and no output schema, the description provides adequate but incomplete context. It clearly states the tool's purpose and exclusions, but doesn't address behavioral aspects like response format, pagination, or error conditions that would be important for an agent to use it effectively. The absence of an output schema means the description should ideally provide some indication of what gets returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all 7 parameters. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions the date-based search concept generally but doesn't provide additional syntax, format, or usage details for individual parameters. Baseline 3 is appropriate when the schema does all the parameter documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 verbs ('search for blocks or pages') and resources ('based on creation or modification dates'), and explicitly distinguishes it from sibling tools by stating 'Not for daily pages with ordinal date titles', which differentiates it from tools like roam_find_pages_modified_today.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 ('Search for blocks or pages based on creation or modification dates') and explicitly states when not to use it ('Not for daily pages with ordinal date titles'), which helps differentiate from roam_find_pages_modified_today. However, it doesn't explicitly mention alternatives like roam_search_by_text or roam_search_by_status for other search criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool performs a write operation ('Add'), includes important behavioral notes on Roam-flavored markdown syntax and linking rules, and specifies prerequisites. It does not cover potential side effects like rate limits or error handling, but adds substantial 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. The markdown notes and prerequisite are necessary but could be slightly more streamlined. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (write operation with 3 parameters, no annotations, no output schema), the description is mostly complete. It covers purpose, usage context, markdown rules, and prerequisites. However, it lacks details on return values or error cases, which would be helpful for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (todos, graph, write_key). The description does not add meaning beyond the schema, such as explaining the format of 'graph' or when 'write_key' is required, but the baseline is 3 since the schema provides adequate parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add a list of todo items as individual blocks') and target resource ('today's daily page in Roam'), distinguishing it from sibling tools like roam_create_page or roam_update_page_markdown. It specifies that each item becomes an actionable block with todo status, providing precise functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage ('to today's daily page') and prerequisites ('Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource'). However, it does not explicitly state when not to use this tool or name alternatives among siblings, such as roam_process_batch_actions for bulk operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that this is a write operation ('Move a block'), implying mutation, but doesn't mention permissions, rate limits, or error handling. The description adds some context by noting it's a wrapper, but lacks details on behavioral traits like whether moves are reversible or what happens on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is 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 earns its place by providing essential information without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 is somewhat incomplete for a mutation tool. It covers purpose and guidelines well but lacks details on behavioral aspects like error responses or side effects. However, it's adequate for basic use, especially with the high schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description doesn't add any meaning beyond what the schema provides (e.g., it doesn't explain parameter interactions or edge cases). Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Move a block to a new location') and the resource ('block'), distinguishing it from sibling tools like roam_create_page or roam_rename_page. It explicitly mentions it's a convenience wrapper for single block moves, which differentiates it from roam_process_batch_actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: it states 'This is a convenience wrapper around roam_process_batch_actions for single block moves,' clearly indicating this tool is preferred for single moves while roam_process_batch_actions should be used for batch operations. No misleading or missing guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it's a read operation (implied by 'data retrieval'), mentions case-sensitivity of the Roam graph, explains client-side post-processing capabilities via regex filtering, and provides tips on query construction. However, it doesn't explicitly mention rate limits, authentication needs, or error handling, 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, use cases, data model reference, tips), but it's quite lengthy with multiple paragraphs and detailed lists. While all content is relevant for this complex tool, it could be more front-loaded with the most critical information. Some sentences in the tips section could be condensed without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, no annotations, no output schema), the description does an excellent job providing context. It explains the tool's advanced nature, provides concrete use cases, documents the Roam data model, and offers query construction tips. The main gap is the lack of output format description (no output schema exists), but otherwise it's quite comprehensive for helping an agent understand when and how to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds some context about the Roam data model (namespaces, attributes, predicates, aggregates) and query tips that help understand how to construct the 'query' parameter, but doesn't provide additional semantic meaning for specific parameters beyond what the schema already offers. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools.' It specifies the verb ('Execute'), resource ('custom Datomic query on the Roam graph'), and distinguishes it from sibling tools by emphasizing 'advanced data retrieval beyond the available search tools.' The title is null, so the description carries the full burden of explaining purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines with a dedicated 'Optimal Use Cases' section listing four scenarios: Advanced Filtering, Highly Complex Boolean Logic, Arbitrary Sorting Criteria, and Proximity Search. It implicitly contrasts with simpler sibling tools like roam_search_by_text or roam_search_by_date by positioning this as an advanced alternative. The guidance is comprehensive and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it creates permanent collections, batches page and content creation efficiently, and requires context preparation. However, it doesn't mention potential failure modes, rate limits, or authentication requirements (though the input schema hints at write_key for some cases).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose statement, use cases, efficiency tip, and prerequisite. While slightly longer than minimal, every sentence adds value. The bulleted list of use cases is efficient, and the information is front-loaded with the core purpose first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no annotations and no output schema, the description provides substantial context: clear purpose, detailed usage scenarios, efficiency characteristics, prerequisite resources, and sibling tool differentiation. The main gap is lack of information about return values or error conditions, but given the comprehensive usage guidance, this is still quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters thoroughly. The description adds some context about 'structured outlines and tables' and 'explicit nesting levels and headings' which aligns with the content parameter, but doesn't provide additional parameter semantics beyond what the schema already specifies. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a new standalone page in Roam') and distinguishes it from siblings by mentioning it's 'the preferred method for creating a new page with an outline in a single step.' It explicitly differentiates from roam_process_batch_actions for adding content to existing pages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides excellent usage guidance with explicit 'Best for' scenarios (5 specific use cases), an explicit alternative tool (roam_process_batch_actions), and a prerequisite instruction ('ensure that you have loaded into context the Roam Markdown Cheatsheet resource'). This covers when to use, when not to use, and prerequisites comprehensively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool creates blocks if they don't exist ('If a parent_string is provided and the block does not exist, it will be created'), returns verification data ('fetches the full nested structure after import for verification'), and mentions rate limits as a concern. However, it doesn't explicitly state whether this is a read-only or write operation, though 'import' implies mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core functionality, followed by important notes. Each sentence adds value, such as API usage considerations and prerequisites. It could be slightly more concise by integrating some details, but overall it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no annotations, no output schema), the description does a good job of covering essential context like behavior, alternatives, and prerequisites. It explains the return value ('Returns a nested structure of the created blocks') and operational notes. The main gap is the lack of explicit mutation disclosure, but it's largely complete for the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description adds some context (e.g., parent_uid is 'preferred for accuracy', parent_string behavior if block doesn't exist), but doesn't provide significant additional semantic meaning beyond what the schema offers. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Import nested markdown content') and target resource ('into Roam under a specific block'), distinguishing it from siblings like roam_create_page or roam_update_page_markdown. It specifies the import mechanism and the nested structure of the content, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use alternatives (e.g., 'For large imports or when rate limits are a concern, consider using roam_process_batch_actions'), prerequisites ('ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource'), and context for parameter choices (e.g., parent_uid is 'preferred for accuracy'). This comprehensive guidance helps the agent select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it's 'non-transactional,' 'API-efficient' with rate limit considerations, supports UID placeholders with `{{uid:name}}` syntax and returns a `uid_map`, requires valid block UIDs for existing blocks, supports Roam-flavored markdown, and has prerequisites like loading the 'Roam Markdown Cheatsheet.' It doesn't explicitly mention error handling or performance limits, but covers most critical aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings for key points and uses bullet-like sections for clarity. It's appropriately sized for a complex tool, but could be slightly more concise by integrating some repetitive advice (e.g., the note about obtaining UIDs is mentioned twice). Most sentences earn their place by adding valuable context or warnings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch operations with multiple action types), no annotations, and no output schema, the description does a good job of providing necessary context. It explains the execution model, UID handling, prerequisites, and when to use alternatives. It could improve by detailing the output structure more explicitly (beyond mentioning `uid_map`) or error scenarios, but it's largely complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some context beyond the schema, such as explaining UID placeholder syntax with examples and noting that `string` supports block embedding with `((UID))` syntax. However, it doesn't provide significant additional semantic meaning for parameters beyond what's in the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch.' It specifies the exact operations (create/update/move/delete blocks) and distinguishes it from siblings by noting it's for 'multiple block operations' and contrasting with simpler alternatives like 'roam_create_outline'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It states: 'Combine all create/update/delete operations into a single call whenever possible. For intensive page updates or revisions, prefer this tool over multiple sequential calls.' It also mentions: 'For simpler, sequential outlines, `roam_create_outline` is often more suitable,' and advises using other tools like `roam_fetch_page_by_title` to obtain UIDs beforehand.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by explaining the smart diff mechanism (preserves block UIDs, generates minimal changes) and operational steps. It mentions the dry_run parameter for previewing changes, which is useful behavioral context. However, it doesn't cover error conditions, rate limits, or authentication needs beyond the write_key parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, bullet points for use cases, numbered steps for mechanics, and an important note. It's appropriately sized for a complex tool, though the 'How it works' section could be slightly condensed as it partially reiterates the opening.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 does a good job covering purpose, usage, and behavior. It explains the smart diff approach and prerequisites. However, it lacks details on return values or error handling, 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal value beyond the schema—it mentions 'smart diff' which relates to the markdown parameter, and 'dry_run' for previewing, but doesn't provide additional syntax or format details. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Update an existing page with new markdown content using smart diff') and distinguishes it from siblings like roam_create_page (creates new) and roam_import_markdown (imports rather than updates existing). It specifies the resource ('existing page') and method ('smart diff'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 ('ideal for syncing external markdown files, AI-assisted content updates, batch modifications') and includes a critical prerequisite ('ensure you have loaded the Roam Markdown Cheatsheet resource'). It implicitly distinguishes from alternatives like roam_create_page for new pages, though it doesn't explicitly name them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it performs verification queries after creation, mentions rate limit concerns for large outlines, and requires loading the 'Roam Markdown Cheatsheet' resource beforehand. However, it lacks details on error handling or response format, which could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose and key usage guidelines. It uses bullet points and bold text for emphasis, but it includes some redundancy (e.g., repeating warnings about duplicates and API usage) and could be slightly more concise by merging related points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (5 parameters, no annotations, no output schema), the description is mostly complete. It covers purpose, usage, parameters, and behavioral aspects like verification and rate limits. However, it lacks details on the output format or error scenarios, which would enhance completeness for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining parameter semantics beyond the schema: it clarifies that 'outline' defines new blocks, warns against including parent block text to avoid duplicates, and explains how 'block_text_uid' works for nesting under existing blocks. This compensates well, though it doesn't cover all parameters like 'graph' or 'write_key' in depth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add a structured outline to an existing page or block' with specific details about customization and nesting. It explicitly distinguishes from sibling tools like 'roam_create_page' for new pages and 'roam_process_batch_actions' for complex nesting, avoiding tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: use 'roam_create_page' for new pages, 'roam_process_batch_actions' for complex nesting or large outlines, and this tool for simpler, contiguous hierarchical content. It also includes specific scenarios like 'Adding supplementary structured content to existing pages' and warnings about duplicate blocks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it abstracts complex nested structures, validates row/column consistency, converts empty cells to spaces (required by Roam), and mentions prerequisites like loading a cheatsheet resource. However, it doesn't cover potential error cases, rate limits, or authentication details, which prevents 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: a concise purpose statement, a bulleted list of reasons to use the tool, an example, and an important note. Every sentence adds value, such as explaining the tool's abstraction benefits and providing practical guidance, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of creating tables in Roam, no annotations, and no output schema, the description does a good job of covering key aspects like purpose, usage guidelines, and behavioral traits. It includes an example and prerequisites. However, it lacks details on error handling, response format, or advanced usage scenarios, which could enhance completeness for a tool with 6 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of headers and rows with an example, clarifying that the first header is typically empty for row labels, and mentioning validation of row/column consistency. It also implicitly relates to parameters like parent_uid and order by discussing where and how the table is created, though not explicitly naming them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Create a table in Roam with specified headers and rows.' It distinguishes itself from sibling tools by focusing on table creation, which is a specific function not covered by other tools like roam_create_outline or roam_create_page. The description also explains the abstraction it provides over Roam's complex nested structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'Why use this tool' section that explicitly outlines when to use this tool (e.g., to avoid error-prone manual creation, for automatic handling of nested structures, and for validation). It also provides an IMPORTANT note specifying a prerequisite: 'Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource.' This gives clear guidance on usage context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
How to claim the server?
If you are the author of the server, you simply need to authenticate using GitHub.
However, if the MCP server belongs to an organization, you need to first add glama.json to the root of your repository.
{
"$schema": "https://glama.ai/mcp/schemas/server.json",
"maintainers": [
"your-github-username"
]
}Then, authenticate using GitHub.
Browse examples.
How to make a release?
A "release" on Glama is not the same as a GitHub release. To create a Glama release:
- Claim the server if you haven't already.
- Go to the Dockerfile admin page, configure the build spec, and click Deploy.
- Once the build test succeeds, click Make Release, enter a version, and publish.
This process allows Glama to run security checks on your server and enables users to deploy it.
How to add a LICENSE?
Please follow the instructions in the GitHub documentation.
Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear on the server after some time, you can manually trigger a new scan using the MCP server admin interface.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/2b3pro/roam-research-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server