Roam Research MCP Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes, such as roam_create_page for new pages versus roam_create_outline for adding to existing pages. However, some overlap exists: roam_search_by_text and roam_search_for_tag both search for blocks, and roam_process_batch_actions can perform tasks covered by simpler tools like roam_add_todo, which might cause confusion in tool selection.
Naming Consistency5/5
All tool names follow a consistent snake_case pattern with a 'roam_' prefix and descriptive verb_noun combinations, such as roam_fetch_page_by_title and roam_search_by_status. This uniformity makes the tool set predictable and easy to navigate for an agent.
Tool Count4/5
With 18 tools, the count is slightly high but reasonable for a comprehensive Roam Research server covering creation, querying, search, and memory management. It avoids being overwhelming by grouping related functionalities, though some tools could potentially be consolidated to reduce complexity.
Completeness5/5
The tool set provides complete coverage for Roam Research operations, including CRUD actions (e.g., roam_create_page, roam_process_batch_actions), advanced querying (roam_datomic_query), various search methods (e.g., by text, tag, date), and specialized features like memory management (roam_remember, roam_recall). No obvious gaps exist for the domain.
Average 3.7/5 across 18 of 18 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'can search for references to a specific block or find all block references,' which hints at functionality but lacks critical details: it doesn't specify output format, pagination, rate limits, authentication requirements, or error handling. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with two sentences that directly state the tool's purpose and key capabilities. There is no wasted language or redundancy. However, it could be slightly more structured by explicitly separating scope and parameter usage, which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (search functionality with optional parameters), lack of annotations, and absence of an output schema, the description is incomplete. It fails to explain what the search returns (e.g., list of blocks, metadata), how results are formatted, or any limitations (e.g., search depth, performance considerations). This leaves the agent with insufficient context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting both optional parameters (block_uid and page_title_uid). The description adds minimal value beyond the schema: it implies the parameters are optional ('can search for references to a specific block') and mentions scope ('within a page or across the entire graph'), but doesn't provide additional syntax, format details, or interaction effects. With high schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does 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 block references within a page or across the entire graph.' It specifies the verb ('search') and resource ('block references'), and distinguishes scope options (page-specific vs. graph-wide). However, it doesn't explicitly differentiate from sibling search tools like roam_search_by_text or roam_search_for_tag, 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: it mentions searching 'within a page or across the entire graph' and references optional parameters, but offers no explicit advice on when to use this tool versus alternatives (e.g., roam_search_by_text for general text searches or roam_search_for_tag for tag-based searches). No prerequisites, exclusions, or comparative context are provided.
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 return format options but doesn't disclose critical behavioral traits: whether this requires authentication, what happens if the title doesn't exist (error vs. null), rate limits, or performance characteristics. 'Fetch' implies read-only, but this isn't explicitly stated, leaving gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences that are front-loaded: the first states the core purpose, the second adds key behavioral detail about output format. Every word earns its place with zero waste or redundancy, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters with full schema coverage but no annotations or output schema, the description is minimally adequate. It covers the basic purpose and output format, but for a fetch operation with potential complexities (e.g., title matching, error handling), it lacks completeness. Without annotations, more behavioral context would be helpful, though the concise nature keeps it at a baseline level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-documented in the schema. The description adds minimal value beyond the schema, only mentioning 'content in the specified format' which echoes the schema's format parameter. It doesn't provide additional context like examples or edge cases, so baseline 3 is appropriate given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetch' and resource 'page by title', specifying what the tool does. It distinguishes from siblings like roam_search_by_text or roam_search_by_date by focusing on exact title matching rather than search operations. However, it doesn't explicitly contrast with roam_fetch_block_with_children, which might be a similar fetch operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling search tools (roam_search_by_text, roam_search_by_date, etc.), there's no indication whether this is for exact title matches versus broader searches, or when to prefer this over roam_fetch_block_with_children. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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' and implies a read operation, but fails to detail performance impacts (e.g., from large result sets), authentication needs, rate limits, or error handling. This is inadequate for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and briefly notes additional features. There is no wasted text, and it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters with full schema coverage and no output schema, the description is minimally complete but lacks depth. It covers the basic purpose and hints at functionality but does not address behavioral aspects like performance or error handling, which are important for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing full documentation for all parameters (limit, offset, sort_order). The description adds minimal value beyond the schema by mentioning 'pagination and sorting options,' which aligns with the parameters but does not elaborate on their semantics or usage. 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/5
Does 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)' with 'pagination and sorting options.' It specifies the verb ('Find'), resource ('pages'), and temporal scope ('today'), but does not explicitly differentiate from sibling tools like 'roam_search_by_date' or 'roam_search_by_text,' which could 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'pagination and sorting options' but does not specify use cases, prerequisites, or exclusions compared to sibling tools such as 'roam_search_by_date' or 'roam_search_by_text,' leaving the agent without contextual direction.
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 describes the tool as providing content and optionally concatenating with custom instructions, but it lacks details on critical behaviors: for example, whether this is a read-only operation, if it requires authentication, what the output format is (e.g., plain text, structured data), or any rate limits. The description is minimal and does not compensate for the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the main purpose ('Provides the content of the Roam Markdown Cheatsheet resource') and adds a conditional detail without unnecessary elaboration. Every word earns its place, making it appropriately sized and well-structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the context: no annotations, no output schema, and 0 parameters, the description is incomplete. It explains what the tool does but lacks essential details for an AI agent, such as the return type (e.g., markdown text, error handling), behavioral traits (e.g., read-only, side effects), or how it integrates with sibling tools. The description does not compensate for the missing structured information, making it inadequate for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameters are documented in the schema. The description mentions an optional 'CUSTOM_INSTRUCTIONS_PATH' parameter, adding semantic meaning beyond the schema by indicating that custom instructions can be concatenated if this path is set. This provides useful context for potential parameter usage, though it's not a formal parameter in the schema. Since there are 0 parameters, the baseline is 4, and the description adds value by hinting at optional behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it provides content from a specific resource (the Roam Markdown Cheatsheet). It specifies the verb 'provides' and the resource 'Roam Markdown Cheatsheet', making the action and target explicit. However, it does not distinguish this from sibling tools like 'roam_import_markdown' or 'roam_search_by_text', which might also involve markdown or content retrieval, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes no guidance on when to use this tool versus alternatives. It mentions an optional feature (concatenation with custom instructions) but does not explain scenarios where this tool is preferred over other content-fetching or markdown-related siblings, such as 'roam_fetch_page_by_title' or 'roam_import_markdown'. There is no explicit when/when-not or alternative tool references, 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. It mentions searching 'across all pages or within a specific page', which adds some behavioral context, but it doesn't disclose critical traits like whether this is a read-only operation, potential rate limits, authentication needs, or what the output format looks like (e.g., list of blocks). For a search tool with no annotations, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Search for blocks with a specific status') and includes key details (status types and scope). There is no wasted verbiage, making it appropriately sized and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., read-only nature, error handling) and output format, which are crucial for a search tool. While the schema covers inputs well, the overall context for an AI agent to use this tool effectively is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning 'across all pages or within a specific page', which loosely relates to the 'page_title_uid' parameter, but it doesn't provide additional syntax or format details. 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and resource 'blocks with a specific status (TODO/DONE)', making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'roam_search_by_text' or 'roam_search_for_tag', which also search blocks but with different criteria, so it falls short of a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'across all pages or within a specific page', providing some context, but it doesn't explicitly state when to use this tool versus alternatives like other search tools (e.g., 'roam_search_by_text' for text-based searches). No exclusions or clear alternatives are named, so it's not fully explicit.
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 the ability to search 'up or down' and 'from a given block,' but doesn't cover critical aspects like whether this is a read-only operation, potential performance impacts, rate limits, authentication needs, or what the output looks like (since there's no output schema). For a search tool with no annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded: two sentences that directly state the tool's purpose and key capability ('search up or down'). There's no wasted verbiage, and every sentence earns its place by conveying essential information efficiently, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (hierarchical search with 4 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain the return values, error conditions, or behavioral nuances like how parameters interact (e.g., if both parent_uid and child_uid are provided). For a search tool without structured output or safety hints, more context is needed to ensure reliable agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are documented in the schema itself (e.g., parent_uid for finding children, child_uid for finding parents, page_title_uid for scoping, max_depth for depth control). The description adds no additional parameter semantics beyond what the schema provides, such as clarifying interactions between parameters or usage examples. With high schema coverage, the baseline is 3, as the description doesn't compensate with extra insights.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for parent or child blocks in the block hierarchy. Can search up or down the hierarchy from a given block.' This specifies the verb ('search'), resource ('parent or child blocks'), and scope ('block hierarchy'), distinguishing it from siblings like roam_search_by_text or roam_search_block_refs. However, it doesn't explicitly differentiate from all siblings (e.g., roam_fetch_block_with_children), keeping it at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating 'Can search up or down the hierarchy from a given block,' which suggests when to use it (for hierarchical searches) but doesn't provide explicit guidance on when to choose this tool over alternatives like roam_search_block_refs or roam_fetch_block_with_children. No exclusions or prerequisites are mentioned, so it's adequate but lacks detailed differentiation.
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 that the tool returns a 'combined, deduplicated list of memories' and mentions optional filtering and sorting. However, it lacks details about permissions needed, rate limits, error conditions, or what constitutes a 'memory' versus other content types. The behavioral disclosure is basic but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that efficiently convey the core functionality and options. It's front-loaded with the main purpose, followed by additional features. There's no wasted text, though it could be slightly more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does and mentions return behavior (deduplicated list), but doesn't detail the output format, error handling, or how memories are defined. With no annotations, more behavioral context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (sort_by and filter_tag). The description adds minimal value beyond the schema by mentioning 'optionally filter blocks with a specific tag and sort by creation date,' which essentially restates what the schema provides. No additional syntax or format details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Retrieve all stored memories on page titled MEMORIES_TAG, or tagged block content with the same name.' It specifies the verb 'retrieve' and resource 'memories' with location details. However, it doesn't explicitly differentiate from sibling tools like roam_search_for_tag or roam_search_by_text, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving memories from specific pages or tagged blocks, but doesn't provide explicit guidance on when to use this tool versus alternatives like roam_search_for_tag or roam_search_by_text. No exclusions or prerequisites are mentioned, leaving the context somewhat open-ended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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. It mentions pagination support and performance considerations for large result sets, which adds useful context beyond the schema. However, it doesn't cover important aspects like error conditions, rate limits, authentication requirements, or what happens when no matches are found, leaving gaps for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences that each serve a purpose: stating the core functionality, explaining pagination support, and providing a usage example. It's front-loaded with the main purpose and avoids unnecessary repetition. However, the third sentence about MEMORIES_TAG feels somewhat tacked on rather than integrated into the flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 6 parameters, no annotations, and no output schema, the description provides adequate but incomplete coverage. It explains the core functionality and pagination but lacks information about return format, error handling, performance characteristics beyond the brief mention, and how results are ordered. The MEMORIES_TAG example helps but doesn't compensate for the missing output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so parameters are well-documented in the structured schema. The description adds minimal value by mentioning the 'limit' and 'offset' parameters specifically for pagination and the MEMORIES_TAG use case for primary_tag, but doesn't provide additional semantic context beyond what's already in the schema descriptions. With high schema coverage, the baseline is 3, and the slight additional context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for blocks containing a specific tag with optional filtering capabilities. It specifies the resource ('blocks') and action ('search for'), distinguishing it from siblings like roam_search_by_text or roam_search_by_date. However, it doesn't explicitly differentiate from roam_search_block_refs which might also involve tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context with 'Use this tool to search for memories tagged with the MEMORIES_TAG,' giving a specific application scenario. However, it doesn't explicitly state when to use this versus other search tools like roam_search_by_text or roam_search_block_refs, nor does it provide clear exclusion criteria or alternatives for similar tag-based operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context beyond the input schema: it explains that memories are stored on the 'daily page' with a specific tag ('MEMORIES_TAG'), mentions optional categories are converted to Roam tags, and provides detailed formatting rules for Roam-flavored markdown (e.g., linking syntax, hashtag usage). However, it doesn't cover aspects like error handling, rate limits, or authentication needs, which could be relevant for a tool that modifies data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence clearly states the tool's purpose. Subsequent sentences provide necessary formatting guidelines and a prerequisite note. While the formatting details are somewhat lengthy, they are relevant for correct usage in the Roam context. There is minimal waste, though the structure could be slightly more streamlined (e.g., integrating the note more seamlessly).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the context: no annotations, no output schema, 2 parameters with full schema coverage, and moderate complexity (involving markdown formatting and tagging), the description is partially complete. It covers the core purpose, storage location, formatting rules, and a prerequisite, but lacks details on behavioral aspects like what happens on failure, whether the operation is idempotent, or example outputs. For a tool that adds data to a system, more behavioral transparency would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('memory' and 'categories'). The description adds some semantic context: it clarifies that 'memory' is 'detail or information to remember' and that 'categories' are 'optional' and 'will be converted to Roam tags.' This provides marginal value over the schema but doesn't significantly enhance understanding of parameter usage or constraints. The baseline of 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.
Purpose4/5
Does 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 MEMORIES_TAG tag and optional categories.' It specifies the verb ('Add'), resource ('memory or piece of information'), and destination ('daily page with MEMORIES_TAG tag'). However, it doesn't explicitly differentiate from sibling tools like 'roam_recall' (which likely retrieves memories) or 'roam_create_page' (which creates pages rather than adding to daily pages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: it mentions storing on the 'daily page' and includes an 'IMPORTANT' note to load the 'Roam Markdown Cheatsheet' resource before use. However, it doesn't explicitly state when to use this tool versus alternatives (e.g., 'roam_create_page' for non-daily pages or 'roam_add_todo' for tasks). The guidance is implied rather than explicit, lacking clear exclusions or comparisons to siblings.
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 the tool returns a nested object structure with specific fields (UID, text, order, children array), which adds context beyond the input schema. However, it doesn't mention potential errors (e.g., invalid UID), performance aspects, or authentication needs, leaving some behavioral traits unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and key details (fetching block with children, depth specification, return structure). Every part earns its place without waste, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (fetching hierarchical data), no annotations, and no output schema, the description is fairly complete. It explains the return structure (nested object with fields), which compensates for the lack of output schema. However, it could improve by mentioning error handling or example usage, but it's sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (block_uid and depth) with descriptions and constraints. The description adds value by explaining that depth controls 'the number of levels deep to fetch children,' but this is largely redundant with the schema. 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/5
Does 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 the scope ('along with its hierarchical children down to a specified depth'). It distinguishes itself from siblings like roam_fetch_page_by_title (which fetches pages, not blocks with children) and roam_search_block_refs (which searches for references, not fetches hierarchical structure).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying 'fetch a block by its UID along with its hierarchical children,' suggesting it's for retrieving nested block structures. However, it doesn't explicitly state when to use this tool versus alternatives like roam_fetch_page_by_title (for pages) or roam_search_hierarchy (which might search but not fetch full nested data). 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.
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 pagination behavior and performance implications ('very large results sets can impact performance'), which is valuable. However, it doesn't mention authentication needs, rate limits, error conditions, or what the return format looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence states the core purpose and scope, the second adds crucial behavioral detail about pagination. Every word earns its place in this efficiently structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 5 parameters and no output schema, the description covers the basic operation and pagination but lacks information about return format, error handling, or performance characteristics beyond a brief warning. With no annotations and no output schema, more behavioral context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by mentioning pagination support for limit/offset parameters, but doesn't provide additional semantic context beyond what's in the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search for blocks containing specific text') and resource ('across all pages or within a specific page'), distinguishing it from sibling tools like roam_search_by_date or roam_search_for_tag. It precisely defines the search scope and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (text-based searches across pages) and implicitly differentiates it from siblings by focusing on text content rather than dates, tags, or references. However, it doesn't explicitly name alternatives or state 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?
No annotations are provided, so the description carries the full burden. It discloses the search behavior and a key exclusion (not for daily pages), but lacks details on permissions, rate limits, pagination, or error handling. For a search tool with no annotations, this is a moderate gap, as it covers basic intent but not operational traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by a critical exclusion. Every sentence earns its place by providing essential guidance without redundancy, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is moderately complete. It covers the purpose and a key exclusion, but lacks details on return values, error cases, or behavioral constraints. For a search tool with 5 parameters and no structured output, it should do more to guide the agent on what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description adds no additional parameter semantics beyond implying date-based filtering, which is already covered in the schema. Baseline 3 is appropriate when the schema does the heavy lifting, with no extra value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search for blocks or pages'), resource ('blocks or pages'), and distinguishing scope ('based on creation or modification dates'). It explicitly differentiates from sibling tools by stating 'Not for daily pages with ordinal date titles,' which distinguishes it from tools like roam_find_pages_modified_today that might handle daily pages differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use this tool ('Not for daily pages with ordinal date titles'), which helps the agent avoid misuse. It also implies usage context by specifying date-based search, distinguishing it from text-based (roam_search_by_text), tag-based (roam_search_for_tag), or status-based (roam_search_by_status) siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior (adding todos as individual blocks with todo status) and includes important usage notes on Roam-flavored markdown syntax, which adds valuable context beyond basic functionality. However, it doesn't mention potential side effects like rate limits 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose, followed by important notes. While informative, the markdown syntax section could be more concise, but overall it maintains good structure without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is reasonably complete. It covers purpose, usage guidelines, and behavioral notes, though it lacks details on return values or error handling, which would be helpful for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the 'todos' parameter as a list of todo item texts. The description adds minimal value beyond this, mentioning that items become 'individual blocks' but not providing additional semantic context about parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add a list of todo items as individual blocks') and target resource ('today's daily page in Roam'), distinguishing it from siblings like roam_create_page or roam_import_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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('add... to today's daily page') and includes a prerequisite ('Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource'), providing clear guidance on timing and preparation.
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 creation tool (implied mutation), it creates 'standalone' pages with 'permanent collections,' and it requires loading a specific resource beforehand. However, it doesn't mention potential side effects like duplicate pages, error conditions, or what happens if the cheatsheet isn't loaded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: purpose statement, use cases in bullet points, and an important prerequisite. While slightly longer than minimal, every sentence adds value. The bullet points could be more concise, but overall the information density is high.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no annotations and no output schema, the description does a good job covering purpose, usage guidelines, and prerequisites. It could be more complete by mentioning what the tool returns (e.g., success confirmation, page reference) or potential error conditions, but given the context signals, it provides substantial guidance for proper use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds some context about 'structured outlines' and 'explicit nesting levels' which aligns with the content parameter's structure, but doesn't provide additional syntax or format details beyond what the schema provides. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a new standalone page in Roam with optional content, including structured outlines, using explicit nesting levels and headings (H1-H3).' It specifies the verb ('create'), resource ('standalone page'), and distinguishes it from siblings by emphasizing it's the 'preferred method for creating a new page with an outline in a single step.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Best for: Creating foundational concept pages... Establishing new topic areas... Setting up reference materials... Making permanent collections of information.' It also includes an important prerequisite: 'Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource.' This clearly defines appropriate use cases and prerequisites.
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 provides 'direct access to Roam's query engine,' notes that 'Roam graph is case-sensitive,' explains that regex filtering is applied 'client-side after the Datomic query,' and offers tips on query construction (e.g., using :block/parents for ancestors, handling case-sensitivity). It doesn't cover rate limits, authentication needs, or error handling, but provides substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, optimal use cases, data model reference, tips) and front-loaded with the core purpose. However, it includes extensive details like the full list of namespaces/attributes and predicates/aggregates, which might be excessive for a tool description—some of this could be referenced elsewhere. Most sentences earn their place by providing actionable guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (custom query execution with 5 parameters) and no annotations or output schema, the description does a good job of providing context. It explains the tool's role, when to use it, behavioral notes (case-sensitivity, client-side filtering), and includes tips for effective querying. It could benefit from examples of return values or error cases, but overall it's quite complete for guiding usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds some context by mentioning 'regex matching on results post-query' and 'client-side post-processing,' which relates to the regexFilter parameter, but doesn't provide significant additional semantic meaning beyond what's in the schema descriptions. This meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools.' This clearly specifies the verb (execute), resource (custom Datomic query on Roam graph), and distinguishes it from sibling tools by emphasizing it's for 'advanced data retrieval beyond the available search tools.' The title being null doesn't affect this clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs alternatives through the 'Optimal Use Cases' section, which lists four specific scenarios (Advanced Filtering, Highly Complex Boolean Logic, Arbitrary Sorting Criteria, Proximity Search). It also implies when not to use it by stating it's for 'advanced data retrieval beyond the available search tools,' suggesting simpler sibling tools like roam_search_by_text or roam_search_hierarchy should be used for basic queries.
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 can locate parent blocks by UID or string match, creates blocks if they don't exist when using parent_string, and returns a nested structure of created blocks. However, it doesn't mention potential side effects like overwriting existing content or error handling, leaving some 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first, followed by operational details and an important prerequisite. Every sentence adds value, though the two-sentence structure could be slightly more streamlined without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no annotations, no output schema), the description is reasonably complete. It covers the tool's purpose, usage context, key behaviors, and prerequisites. However, without an output schema, it doesn't fully explain the return value's structure, and some behavioral aspects like error conditions are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, mainly emphasizing the preference for UID over string matching and the creation behavior for parent_string. This meets the baseline of 3 since 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/5
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 verbs ('import nested markdown content') and resources ('into Roam under a specific block'), distinguishing it from siblings like roam_create_page or roam_add_todo which handle different operations. It precisely defines what the tool does beyond just the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it specifies when to use this tool (for importing markdown content under a parent block), mentions prerequisites (loading the 'Roam Markdown Cheatsheet' resource), and distinguishes it from alternatives by focusing on nested content import rather than page creation or querying. The 'IMPORTANT' note adds clear context for proper use.
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 does well by describing the execution order ('Actions are executed in the provided order'), transactional nature ('non-transactional batch'), and specific capabilities like temporary UIDs for nested blocks and support for Roam-flavored markdown. However, it doesn't mention error handling, rate limits, or authentication requirements, which are common behavioral traits for batch operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds valuable information about usage, prerequisites, and alternatives. While comprehensive, it could be slightly more concise by combining some of the guidance sentences, but overall it earns its place with useful content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a batch operation tool with no annotations and no output schema, the description does well to cover execution behavior, prerequisites, alternatives, and specific capabilities. It mentions the need for UIDs from other tools and references the markdown cheatsheet resource. The main gap is the lack of information about return values or error responses, which would be helpful given there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single 'actions' parameter thoroughly. The description adds some context about how parameters are used (e.g., 'For creating nested blocks, you can use a temporary client-side UID...'), but doesn't provide significant additional semantic meaning beyond what the schema already specifies. This meets the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch,' specifying both the verb (execute) and resource (block actions). It distinguishes from siblings by explicitly mentioning 'roam_create_outline' as an alternative for simpler outlines, showing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs alternatives: 'For simpler, sequential outlines, `roam_create_outline` is often more suitable.' It also specifies prerequisites: 'Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource,' and mentions when other tools are needed first: 'Tools like `roam_fetch_page_by_title` or other search tools can be used to retrieve these UIDs before executing batch actions.'
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 explains key behaviors: the tool creates new blocks (implied mutation), warns about duplicate creation if parent blocks are included, and clarifies that the outline defines new blocks to be created. However, it lacks details on error handling, permissions, or rate limits, which are common for mutation tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, but it includes a lengthy 'Best for' list and an 'IMPORTANT' note that, while useful, could be more concise. Most sentences earn their place by providing critical guidance, though some redundancy exists in the nesting explanations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with hierarchical data), no annotations, and no output schema, the description does a good job covering usage scenarios, alternatives, and parameter semantics. However, it lacks details on return values, error cases, or system limitations, leaving some gaps in contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains that `outline` defines new blocks, clarifies how to nest under existing blocks using `block_text_uid`, and warns against including parent blocks to prevent duplicates. This enhances understanding but does not fully compensate for all parameter nuances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Add a structured outline to an existing page or block') and resources ('page or block'), and explicitly distinguishes it from the sibling tool `roam_create_page` for creating new pages with outlines. This provides precise differentiation and avoids ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives: it specifies to use `roam_create_page` for new pages with outlines, warns against including parent blocks in the outline to avoid duplicates, and recommends `roam_process_batch_actions` for complex nesting or granular control. It also includes a prerequisite to load the 'Roam Markdown Cheatsheet' resource before use.
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:

[![roamMCP MCP server](https://glama.ai/mcp/servers/camiloluvino/roamMCP/badges/card.svg)](https://glama.ai/mcp/servers/camiloluvino/roamMCP)

Score Badge

Copy to your README.md:

[![roamMCP MCP server](https://glama.ai/mcp/servers/camiloluvino/roamMCP/badges/score.svg)](https://glama.ai/mcp/servers/camiloluvino/roamMCP)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/camiloluvino/roamMCP'

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