Roam Research

Server Quality Checklist

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

Latest release: v3.1.0
Disambiguation4/5
Each tool has a distinct primary purpose, and descriptions include explicit disambiguation notes (e.g., get_subpages vs search_hierarchy). However, the large number of search/find tools (search_by_text, search_for_tag, search_by_status, search_by_date, find_pages_modified_today) can still cause confusion, so not a perfect 5.
Naming Consistency3/5
All tools use snake_case and the `roam_` prefix, but action verbs are inconsistent: fetch, get, search, find, create, add. Search tools mix preposition patterns (search_by_text, search_for_tag, search_block_refs), and two tools are noun phrases (roam_markdown_cheatsheet, roam_datomic_query).
Tool Count3/5
25 tools is at the high end of the 'feels heavy' range. The complexity of Roam's data model justifies many operations, but some search variants could be consolidated. The count is not extreme, but it is on the boundary.
Completeness4/5
The set covers page/block creation, retrieval, update, batch operations, rich search, memory, table creation, markdown import, and custom Datomic queries. Explicit page/block deletion tools are missing, though batch actions include delete. There is no general 'list all pages' tool, but search_by_text with page_titles scope partially fills this gap.
Average 4.3/5 across 25 of 25 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 2 community issues answered or closed in the last 6 months
- No commit activity data available
- Last stable release on August 9, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description only needs to add context. It adds that results are deduplicated and that 'conventions change how results are read, not just written,' which is a valuable behavioral caveat. No contradiction with annotations.
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 two paragraphs; the first is a single dense sentence covering core behavior, the second is a necessary warning. It is efficient with no redundant content, though the first sentence is long and complex.
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?
The description covers the dual retrieval source, deduplication, optional filtering/sorting, and a per-session prerequisite. It also states the return type ('combined, deduplicated list'). For a simple read-only tool with good annotations, this is adequate, though it could clarify the exact format of the returned list.
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 coverage is 100%, with all four parameters described. The description mentions filter_tag and sort_by but does not add new semantic detail beyond the schema, so the baseline score of 3 is appropriate.
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 primary function: 'Retrieve all stored memories on page titled ROAM_MEMORIES_TAG, or tagged block content with the same name.' It specifies the resource (memories), the source (page or tags), and the output (deduplicated list). This distinguishes it from sibling search tools by focusing on memory recall.
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 explicitly mandates calling roam_get_guidelines before using this tool, which is a clear prerequisite. However, it does not explicitly contrast with alternative tools like roam_search_for_tag, though the memory-specific scope implies the intended use case.
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?
Annotations are all false, providing no behavioral safety hints (e.g., readOnlyHint=false implies a write, but no further detail). The description compensates by disclosing that the tool writes to the daily page, applies a tag and optional categories, and includes a markdown syntax warning to avoid formatting errors. It does not mention permission requirements or rate limits, but for a write tool with no other annotation coverage, it adds substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a clear one-sentence purpose, followed by a detailed markdown note and a prerequisite warning. While the markdown note is verbose, it provides essential usage guidance. The structure is front-loaded and the additional paragraphs earn their place.
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?
The description covers the core purpose, storage location, tag behavior, and prerequisite calls, making it sufficient for an agent to invoke the tool correctly. It does not mention heading or parent_uid options, but these are fully described in the schema. Given the high schema coverage and output schema, the description is adequately complete, though it could briefly note that headings/parent_uid can organize memories.
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?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the storage behavior (daily page + tag), the optionality of categories, and a detailed markdown note relevant to formatting memory content and categories. However, the phrase '(unless include_memories_tag is false)' is ambiguous, potentially implying categories are also omitted when the tag is disabled, which conflicts with the schema's separate handling.
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 action ('Add a memory or piece of information to remember') and specifies the storage location (daily page with ROAM_MEMORIES_TAG tag). This distinguishes it from siblings like roam_add_todo (adds tasks) and roam_recall (retrieves memories).
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 clear context for use (storing memories) but does not explicitly state when to use this tool versus alternatives. It includes a prerequisite instruction to call roam_get_guidelines and load the markdown cheatsheet, but lacks exclusionary guidance such as 'use roam_add_todo for tasks' or 'use roam_recall to fetch memories.'
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?
Annotations already declare this tool destructive and idempotent. The description adds useful context beyond annotations by requiring a call to roam_get_guidelines and noting that conventions affect reads as well as writes. This provides behavioral nuance not captured in the structured fields.
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 brief (two sentences) and front-loaded with the core purpose. The second sentence conveys a critical prerequisite but is slightly convoluted with 'reads included.' Overall, it is compact and earns its place, though the phrasing could be clearer.
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 simple rename tool with a complete input schema, output schema, and annotations covering safety, the description adds the essential prerequisite and identification method. It does not explain error conditions, but these are not critical for correct tool usage in most contexts.
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 for all parameters, including guidance on using old_title or uid. The description adds no additional parameter semantics beyond the phrase 'current title or UID,' which merely mirrors the schema. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Rename a page by changing its title.' It also specifies the identification method ('by current title or UID'), distinguishing it from sibling tools like create_page or update_page_markdown.
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 gives explicit usage guidance by instructing the agent to call roam_get_guidelines before using this tool, including a rationale about conventions. However, it does not name alternative tools or state when not to use this tool, so it stops short of a full 5.
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?
Annotations indicate a write operation (readOnlyHint: false) but provide limited safety info. The description adds valuable context: it automatically handles the {{[[table]]}} container, validates row/column consistency, and converts empty cells to spaces. It also mentions the session prerequisite, giving the agent important operational details beyond the structured 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 well-structured and front-loaded with the core action. The 'Why use this tool' bullets are concise and purposeful, the example is helpful, and the IMPORTANT note is relevant. No sentence is wasted.
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 params), the description provides purpose, rationale, an example, and a prerequisite. The output schema exists, so return-value details are not necessary. It lacks explicit edge-case handling but is complete enough for an agent to use 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?
Schema description coverage is 100%, so the schema already documents all parameters. The description's example adds a concrete illustration of how headers and rows map to a table, but it does not add significant new semantics beyond what the schema provides. Baseline of 3 is appropriate.
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 opens with 'Create a table in Roam with specified headers and rows,' which is a specific verb+resource statement that clearly distinguishes this tool from siblings like roam_create_outline or roam_create_page. It also explains the tool abstracts Roam's complex nested table structure, reinforcing its unique purpose.
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 'Why use this tool' section explicitly states when this tool is beneficial (avoiding error-prone manual creation, handling table containers, validating consistency). It also provides a clear prerequisite: call roam_get_guidelines and load the Markdown Cheatsheet before use. However, it does not explicitly name alternatives or state when not to use it, though the context is clear.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by warning that graph conventions affect how results are read, which is not captured by annotations or schema. This is useful and complements the structured metadata.
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: two sentences achieve the core purpose and add a critical usage warning. There is no filler or redundant explanation. The important guideline is highlighted with 'IMPORTANT' and placed prominently, making it effective.
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 read-only fetch tool with rich schema descriptions and annotations, the description is sufficiently complete. It covers the core function, return format note, and the prerequisite guideline call. There is no output schema, but the format parameter description in the schema explains expected outputs. Minor gaps like behavior on missing pages are acceptable for this tool type.
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 schema has 100% coverage with detailed descriptions for all parameters, including the format enum and its behavior. The description adds no additional parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
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 verb 'Fetch' and the resource 'page by title', making the tool's purpose unambiguous. It is specific enough to distinguish from sibling tools like roam_fetch_page_full_view or roam_fetch_block, which operate on different inputs or views.
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 explicitly instructs the agent to call roam_get_guidelines before every session, even for reads, adding important prerequisite guidance. It does not mention specific alternative tools or exclusion criteria, but the context of use is clear from the verb and resource.
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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: mirrors Roam UI, groups backlinks by source page, includes breadcrumbs, and mentions max_references to prevent timeouts. No contradictions with 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?
Two sentences of purpose and usage, plus one important prerequisite note. Every sentence earns its place, front-loaded with the core purpose. No fluff or redundancy.
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 complex read tool with no output schema, the description well explains the response composition: page content, grouped backlinks, breadcrumbs, and child expansion depth. It also includes a session-level prerequisite. Minor gap: no explicit mention of pagination beyond max_references, but that is partially covered in 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 parameters are already fully documented. The description's references to 'children expanded to the specified depth' and 'max_references' merely restate what the schema provides without adding new semantic meaning.
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 starts with 'Fetch a complete page view' which clearly identifies the verb, resource, and scope. It distinguishes itself from sibling tools by specifying it includes linked references grouped by source page with breadcrumb context, unlike a simple 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use case: 'Use this when you need the full picture of a page'. Also instructs to call roam_get_guidelines before use, which is a prerequisite. Does not explicitly name alternatives to exclude, but gives clear context for when to choose this tool.
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?
Beyond the annotations (read-only, idempotent), the description adds a behavioral caveat: conventions change how results are read, and it requires calling roam_get_guidelines. This enriches the agent's understanding without contradicting 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?
Two impactful sentences: the main action and an important prerequisite. The description is front-loaded with the core purpose and wastes no words.
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 read-only nature, schema coverage, and annotations, the description covers the core function, the required guideline call, and a behavioral caveat. It lacks explicit return format or timezone clarification for 'midnight', but these are minor gaps.
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 coverage is 100%, so parameters (limit, offset, sort_order, graph, write_key) are already fully described in the schema. The description only mentions pagination and sorting generically without adding new parameter-specific meaning, keeping the baseline at 3.
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 identifies the action ('Find') and the resource ('pages modified today'), with a precise time scope ('since midnight'). It is easily distinguished from sibling tools like roam_search_by_date or 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context for when to use the tool (for pages modified today) and a critical prerequisite (call roam_get_guidelines once per session). However, it does not mention alternatives or exclusions, so it falls short of a 5.
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?
The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context by requiring a call to roam_get_guidelines and warning that conventions change how results are read, going beyond what annotations and schema provide.
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 long, front-loaded with the core action and followed by a critical exclusion and warning. Every sentence earns its place, and the formatting makes the important prerequisite prominent.
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?
With 7 parameters, no output schema, and rich annotations, the description plus schema is almost sufficient. It provides a mandatory guidelines call and exclusion, but could benefit from a brief note on result format or edge cases like end_date inclusivity.
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 provides 100% coverage for all 7 parameters, so the baseline is 3. The description does not add any parameter-specific details, examples, or additional meaning beyond the 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 tool searches blocks/pages by creation or modification dates, and includes an explicit exclusion for daily pages with ordinal date titles. It is specific and actionable, but does not explicitly name sibling alternatives to differentiate from.
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 says 'Not for daily pages with ordinal date titles' (when-not) and instructs to call roam_get_guidelines once per session before using the tool (prerequisite). This provides clear usage context, even though it does not name an alternative tool.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds a meaningful behavioral nuance: graph conventions can change how results are read, not just written, and guidelines must be fetched once per session. This goes beyond the annotations and aids correct usage.
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: the first states the purpose, the second delivers a critical usage prerequisite. It is front-loaded, concise, and every word adds value. No redundancy.
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 and full schema coverage, the description is complete for selection and invocation. It discloses the prerequisite call, the scope options, and the status filter. It does not describe return format, but search tools without output schema are often self-explanatory. Minor gap: no mention of exclude/include filters beyond the schema, but those are documented there.
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 provides 100% coverage with detailed descriptions for all 6 parameters. The description does not add syntax or format details beyond the schema, so the baseline 3 is appropriate. The scope behavior (all pages vs specific page) is already captured in the page_title_uid parameter 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 it searches for blocks by status (TODO/DONE) across all pages or a specific page. The verb 'search' plus resource 'blocks' and filter 'status' makes the purpose specific and distinguishes it from sibling search tools like roam_search_by_text or roam_search_by_date.
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 an explicit prerequisite: call roam_get_guidelines before using this tool, even for reads. It also mentions the optional scope (all pages vs a specific page). However, it does not explicitly contrast with alternative search tools or state when-not-to-use, so it falls short of a 5.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavior beyond annotations by mentioning pagination via limit/offset and the important note that conventions change how results are read, requiring a one-time call to roam_get_guidelines. This enriches the agent's understanding of how to invoke and interpret results.
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 short paragraphs, front-loaded with the primary purpose. The second paragraph is an important, non-obvious prerequisite that earns its place. No wasted words.
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 no output schema, the description doesn't detail the return structure, but the purpose implies a list of blocks. It covers the key parameters, pagination, page scoping, and a critical guideline call. This is sufficient for a read-only search tool with good annotation coverage.
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 all 8 parameters are documented. The description briefly references primary_tag, page_title_uid, limit, and offset, but doesn't add meaningful semantics beyond the schema—it mostly repeats the schema's parameter descriptions. Baseline 3 is appropriate.
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 opens with 'Search for blocks containing a specific tag', which clearly states the verb (search) and resource (blocks with a tag). It also differentiates from sibling search tools by emphasizing tag-based search and gives a concrete use case ('search for memories tagged with the ROAM_MEMORIES_TAG').
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?
It provides clear context with 'Use this tool to search for memories tagged with the ROAM_MEMORIES_TAG' and instructs to call roam_get_guidelines first. It doesn't explicitly name alternatives or when-not cases, but the tag-focused purpose and required preliminary call give sufficient guidance.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds valuable behavioral context: the ability to search both up and down, and the critical caveat that per-graph conventions affect how results are read. This goes beyond the annotations without contradicting them.
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 short paragraphs: the first front-loads the core purpose, the second delivers an essential prerequisite note. No filler words, every sentence earns its place, and the structure is easy to scan.
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 (6 optional params, no output schema), the description covers the essential behavioral scope and a critical prerequisite. It does not explain edge cases like providing both parent_uid and child_uid, or default behavior when neither is given, but the annotations and schema fill many gaps, making the description reasonably complete for a read-only search 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?
The input schema provides 100% coverage with descriptions for all six parameters, so the baseline is 3. The description adds minimal extra meaning beyond the schema, mainly correlating 'from a given block' with parent/child UID parameters. It does not elaborate on parameter interactions (e.g., mutual exclusivity), but the schema already handles the basics.
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 states a specific action ('Search for parent or child blocks') on a specific resource ('block hierarchy'), and clarifies the directional capability ('up or down') from a given block. This clearly distinguishes it from sibling search tools like roam_search_by_text or roam_search_by_status, which operate on content or status rather than hierarchy.
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 makes it obvious when to use this tool: when you need to traverse parent/child relationships in the block hierarchy. It also provides a mandatory prerequisite instruction to call roam_get_guidelines once per session, which is concrete usage guidance. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of the strongest 'when-not' clarity.
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?
Annotations indicate a write operation (readOnlyHint=false) and no idempotency/destructive hints. The description adds context beyond annotations by explaining the tool 'batches page and content creation efficiently' and requiring the user to consult guidelines beforehand. However, it does not disclose edge-case behaviors such as what happens if the page already exists, which would be useful for a creation 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 well-structured with a clear opening sentence, a 'Best for' list, an efficiency tip, and an important prerequisite note. It is slightly longer than necessary (the best-for list has some overlap), but every section earns its place and it is front-loaded with the core purpose.
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 (nested content arrays, table support, headings) and the detailed input schema, the description provides sufficient context: it explains the structure of content, highlights the ability to mix text and tables, and gives usage boundaries. It could mention conflict behavior for existing pages, but overall it is quite complete for a creation 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?
The input schema has 100% parameter description coverage, so the schema carries the burden. The description restates general capabilities (outlines, tables, headings) but does not add specific parameter-level semantics beyond what the schema already explains. Thus the baseline 3 applies.
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 function: 'Create a new standalone page in Roam with optional content, including structured outlines and tables, using explicit nesting levels and headings (H1-H3).' It also distinguishes itself from siblings by noting it is 'the preferred method for creating a new page with an outline in a single step' and contrasts with 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance through a 'Best for:' list covering foundational pages, new namespaces, reference materials, and permanent collections. It also gives an exclusion: 'For adding content to existing pages, use roam_process_batch_actions instead,' and includes a prerequisite instruction to call roam_get_guidelines and load the Markdown Cheatsheet before using.
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?
Annotations already mark this as read-only and idempotent, and the description aligns with that by stating it 'fetches' and 'returns' data. It adds valuable behavioral context beyond the annotations: the graph's conventions can change read semantics, and the response includes a specific ancestors array shape when requested.
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 short paragraphs with no filler. The first sentence states the core function and return values, and the second conveys an essential prerequisite in an 'IMPORTANT' callout. Every sentence earns its place and the structure is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the exact return fields. The mandatory prerequisite for roam_get_guidelines is highlighted, and all parameters are covered by the schema. For a read-only fetch tool with clear sibling context, this is fully adequate.
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 coverage is 100%, so the parameter descriptions already document depth, graph, block_uid, write_key, and include_ancestors. The description adds minimal extra semantic value beyond restating those concepts in prose (e.g., 'children down to a specified depth' maps to depth), but it does not introduce information absent from the schema.
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 begins with a specific verb and resource: 'Fetch a block by its UID' with optional children and ancestors, which clearly distinguishes it from page-level fetch siblings like roam_fetch_page_by_title and roam_fetch_page_full_view. It also enumerates the return fields, reinforcing what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs the agent to call roam_get_guidelines once per session before using the tool, including for reads, and explains that conventions affect how results are read. It does not explicitly name alternative tools or provide exclusion criteria, but the prerequisite and context are clear.
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?
Annotations already declare readOnlyHint=false and destructiveHint=true, so the description does not need to restate these. It adds context about being a wrapper around batch actions and the importance of graph-specific guidelines. However, it does not disclose additional behavioral details such as whether the move is atomic, if child blocks are moved recursively, or the exact impact on references. With annotations covering the safety profile, a 3 is appropriate.
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 three sentences, each earning its place. The first sentence states the action, the second frames it as a wrapper alternative, and the third provides a critical workflow prerequisite. It is front-loaded and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/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 (5 parameters, 2 required, output schema present), the description covers the essential context: what the tool does, how it relates to sibling tools, and the required pre-use step. The output schema handles return values, and annotations handle safety traits, so the description is complete for an agent to select and invoke correctly.
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 for all five parameters, so the description does not need to explain each parameter. It does add a high-level semantic cue ('different parent or position') that maps to parent_uid and order, but this is already explicit in the schema. The description adds marginal value over the schema, matching the baseline of 3.
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 opens with 'Move a block to a new location' which is a specific verb+resource action, and immediately clarifies the scope: 'different parent or position'. It also distinguishes itself from the sibling tool by explicitly calling itself a 'convenience wrapper around roam_process_batch_actions for single block moves', making its 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool—for single block moves—by positioning it as a wrapper around the batch action tool, implying batch actions would be used for multiple moves. It also includes an explicit prerequisite: 'call roam_get_guidelines for this graph once per session', with a brief rationale. This is direct usage guidance.
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?
Annotations already declare the tool read-only, idempotent, and non-destructive, lowering the bar. The description adds a meaningful behavioral note: graph conventions affect how results are read, not just written, implying results can vary between graphs. It also mentions pagination support, though the schema already documents limit/offset.
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 compact: two sentences covering core functionality and a one-sentence important note. It front-loads the primary purpose, explains the alternate scope, then delivers the essential prerequisite. Every sentence earns its place without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters but only 1 required, full schema coverage, and complete annotations, the description adds the crucial missing context: a session-level prerequisite to call roam_get_guidelines because conventions affect reads. The namespace prefix example clarifies a non-obvious mode. No output schema exists, but the return value for a block/page search tool is self-evident.
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% for all 8 parameters, so the baseline is 3. The description's mentions of `scope: 'page_titles'`, the namespace prefix example, and pagination via `limit`/`offset` all reinforce but do not add substantive meaning beyond what the parameter descriptions already provide.
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 opens with 'Search for blocks containing specific text across all pages or within a specific page,' a specific verb and resource. It clearly distinguishes the free-text blocks search from the namespace-prefix page_titles mode, and the availability of these two modes helps set it apart from sibling search tools like roam_search_for_tag or roam_search_by_status.
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 gives clear usage context: it tells the agent to use scope 'page_titles' for namespace prefix searches and includes an 'IMPORTANT' instruction to call roam_get_guidelines once per session because conventions change how results are read. It lacks explicit exclusions or direct references to sibling alternatives, but the context is strong enough to guide appropriate selection.
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?
Annotations already mark readOnly=false, and the description adds that each item becomes an 'actionable block with todo status', and provides markdown linking rules. This is useful behavioral context beyond what annotations convey.
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 main purpose is stated in a single, direct sentence. The markdown note and IMPORTANT prerequisite are structured with labels and are relevant to correct use. It is slightly long, but each part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values don't need to be explained. The description covers the action, the effect on blocks, markdown syntax details, and the required prerequisite call to roam_get_guidelines, making it complete for an agent to invoke correctly.
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 already describes all three parameters with 100% coverage, so the baseline is 3. The description adds valuable markdown syntax guidance for the 'todos' parameter text, such as [[link]] and #[[multiple words]], which increases the score.
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 uses a specific verb ('Add') and resource ('today's daily page'), and clearly states that each item becomes an 'individual block' with todo status. This distinguishes it from sibling tools like roam_create_outline or roam_import_markdown.
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?
It clearly states when to use: adding todos to today's daily page. It also gives an explicit prerequisite: call roam_get_guidelines and load the Roam Markdown Cheatsheet before use. It doesn't explicitly mention alternatives or when not to use, so a 4 is appropriate.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by noting it 'prevents common syntax errors' and 'guides tool selection,' which goes beyond annotations. It doesn't describe the output format, but for a read-only reference the annotations carry the main safety burden.
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 long but front-loaded with the main purpose and then organized into a categorized list. Each sentence adds value, and the IMPORTANT warnings are clearly highlighted. It is appropriately detailed for a comprehensive reference tool, though slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only reference tool with no output schema, the description is complete: it lists the full scope of content covered, provides usage prerequisites, and includes warnings about guidelines. It explains why to load it and mentions the companion function. No significant information is missing.
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%, as both parameters (graph, write_key) have descriptions in the schema. The tool description itself does not mention parameters, but because the schema fully documents them, the baseline is 3. No additional parameter semantics are needed.
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 opens with a clear verb+resource: 'Provides the comprehensive Roam syntax reference.' It enumerates a detailed list of covered topics (formatting, links, queries, diagrams, etc.), which distinguishes it from sibling tools like roam_create_table or roam_add_todo. The purpose is unmistakable and specific.
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?
It explicitly instructs 'Always load this cheatsheet before creating or updating Roam content' and explains it prevents syntax errors and guides tool selection. It also names a prerequisite: 'call roam_get_guidelines for this graph once per session before using this tool.' This is clear when-to-use guidance with an alternative tool mentioned.
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?
Annotations already declare readOnlyHint and destructiveHint, but the description adds meaningful context: results must be interpreted based on graph conventions (calling roam_get_guidelines even for reads). This goes beyond the structured annotations by warning that behavior depends on per-graph conventions.
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 short paragraphs: a focused purpose statement followed by a critical warning. Every sentence is useful, no filler, and the most important usage instruction is front-loaded with 'IMPORTANT.'
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 full schema coverage, read-only annotations, and lack of an output schema, the description sufficiently explains the tool's capability and a key prerequisite. It could mention default behavior when no parameters are provided, but 'find all block references' is already implied, so it is nearly complete.
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?
Schema covers all parameters with descriptions, providing a solid baseline. The description adds relationship semantics: block_uid targets a specific block, title targets page references, and page_title_uid scopes the search to a page or graph-wide. This helps agents understand how to combine parameters effectively.
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 'Search for block references within a page or across the entire graph' and lists specific modes (specific block, page title, all references). This makes the tool's purpose unambiguous and distinguishes it from sibling text-search tools like roam_search_by_text, even though no alternatives are named.
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 conveys when to use the tool (searching for references) and gives an explicit directive to call roam_get_guidelines first due to convention-dependent behavior. It does not explicitly compare with alternative search tools for when not to use it, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond annotations: it notes case-sensitivity, explains that regex filtering is applied client-side after the query, and warns that graph conventions affect results. Annotations already declare readOnly, idempotent, and non-destructive, and the description does not contradict them; it enriches the agent's understanding of side effects and result interpretation.
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 lengthy but well-structured with sections (Optimal Use Cases, data model, predicates, tips) and all content is relevant to using the tool effectively. It front-loads the purpose and uses bold headers for scannability, though a slight trim could make it more concise.
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 complex Datomic query tool, the description covers most essential context: syntax, use cases, data model, predicates, and a required guideline call. However, it does not describe the return format beyond mentioning client-side filtering, and could benefit from noting potential errors or performance implications, so it isn't fully complete.
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?
Schema coverage is 100%, so the baseline is 3, but the description adds significant value by providing an example Datalog query, listing predicates and aggregates, and explaining the data model namespaces. This goes beyond the schema's parameter descriptions and helps the agent construct correct queries, especially for the 'query' parameter.
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 custom Datomic queries on the Roam graph for advanced data retrieval, explicitly distinguishing it from search tools. It further lists specific advanced use cases (regex filtering, complex boolean logic, arbitrary sorting, proximity search), 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description has an 'Optimal Use Cases' section that clearly specifies when to use this tool (advanced filtering, complex boolean logic, etc.), and the opening sentence implies it should be used beyond the available search tools. It also mandates calling roam_get_guidelines before use, but doesn't explicitly name alternative tools for contrast or state when not to use it, so it falls short of a 5.
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?
Beyond the annotations (write, non-destructive), the description discloses two important behaviors: it auto-creates a missing parent block when `parent_string` is used, and it fetches the full nested structure post-import for verification, adding rate-limit context. This is valuable extra transparency, though it does not detail all side effects (e.g., how existing content is affected).
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 main purpose. It uses a clear structure with an API usage note and an important prerequisite. While slightly longer due to the usage warnings, every sentence serves a purpose and there is no fluff.
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 an 8-parameter tool with a full output schema, the description covers the core behavior, parameter lookup logic, rate-limit implications, and required preconditions. It does not explicitly cover error cases or edge conditions, but the schema and output schema fill many gaps, making it reasonably complete.
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?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the preference order (parent_uid/page_uid over parent_string) and clarifying that `parent_string` will create a new block if it doesn't exist. This goes beyond the schema definitions and helps agents choose the right parameters.
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 'Import nested markdown content into Roam under a specific block' with a specific verb, resource, and location. It distinguishes itself from siblings by detailing how the parent block is located (UID or exact string match) and refers to the alternative tool `roam_process_batch_actions` for large imports.
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?
It provides explicit usage guidance: UID is preferred over string match, and it names an alternative for large imports or rate-limit concerns. It also instructs to call `roam_get_guidelines` and load the Markdown Cheatsheet before use, covering prerequisites and when-not-to-use scenarios.
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?
The description goes beyond the annotations by disclosing non-transactional execution, ordered actions, UID placeholder behavior with uid_map responses, and the requirement for valid block UIDs. It also notes that existing-block actions often need page/block UIDs first. The destructiveHint annotation is consistent with the write operations described; no contradiction.
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 long but well-structured with bold section labels and examples. It contains some repetition (e.g., 'For actions on existing blocks' appears twice), but each sentence contributes either usage guidance, parameter enrichment, or prerequisite context. The front-loaded rate-limit note is practical.
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 and the presence of an output schema (indicated but not shown), the description covers the essentials: what the tool does, when to use it, prerequisites for UIDs, nested-block placeholder mechanics, response shape, and the guideline prerequisite. It could mention failure semantics more explicitly, but the non-transactional note covers the key risk.
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?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the {{uid:name}} placeholder syntax with a concrete example, describing the structure of the uid_map response, and noting that Roam-flavored markdown including block embeds is supported in the 'string' property.
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 opens with a clear verb-resource pairing: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch.' It also brands itself as 'the most API-efficient tool for multiple block operations,' which distinguishes it from siblings like roam_create_outline and roam_move_block.
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?
Explicit usage guidance is provided: 'Combine all create/update/delete operations into a single call whenever possible' and 'For simpler, sequential outlines, roam_create_outline is often more suitable.' It also directs users to call roam_get_guidelines once per session and to use search tools like roam_fetch_page_by_title to obtain UIDs.
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?
The description goes beyond the annotations (which are all false) by disclosing that the tool 'performs verification queries after creation' and warns about the risk of duplicate blocks if the parent block's text is included in the outline array. It also clarifies that the outline parameter defines new blocks, which is key behavioral context. However, it does not mention idempotency failure behavior or partial-failure details, so it is not fully exhaustive.
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 longer than strictly necessary but well-structured with a clear opening sentence, bulleted 'Best for' list, and a separate API Usage Note. Each section adds value without redundancy, and the most essential information is front-loaded. It earns a 4 rather than 5 due to its length, though it remains focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/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, nested outline structure), the description is remarkably complete. It covers purpose, usage alternatives, API rate-limit implications, common use cases, and even a prerequisite instruction (call roam_get_guidelines). The existence of an output schema further reduces the need to describe return values, so there are no significant gaps.
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 already provides 100% coverage of parameter descriptions, so the baseline is 3. The description adds meaningful semantic nuances beyond the schema, particularly for the `outline` parameter: it explains that levels are relative to the parent block, and warns against including the parent block's text. This extra guidance helps prevent common usage errors.
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 function: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels.' It distinguishes itself from the sibling tool `roam_create_page` by explicitly noting that tool should be used for creating new pages with outlines. The verb-resource pairing is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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: 'To create a new page with an outline, use the `roam_create_page` tool instead' and 'For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.' It also includes a 'Best for' list and a clear exclusion criterion, making the decision process straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond these: it returns `roamSyntax` on every call, returns `exists:false` instead of failing when no page exists, returns today's daily note title, and explains that conventions affect interpretation/presentation, not just writing. No contradiction with annotations.
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 longer than the absolute minimum but well-structured: purpose, special return value, usage instruction, sibling differentiation, and existence behavior are each in their own sentence/paragraph. Every sentence earns its place, though it could be tightened slightly without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains what is returned (user conventions, roamSyntax, daily note title, exists:false), why it must be called before other tools, and the behavior when no guidelines page exists. It fully covers the operational context a read tool with no output schema needs.
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 provides 100% coverage for both parameters (`graph` and `write_key`) with descriptions. The description adds no new parameter-specific meaning beyond noting the guidelines page is 'configurable per graph', which is already implied by the schema. Baseline 3 is appropriate 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 opens with a specific verb and resource: 'Retrieve this graph's user-defined agent conventions', and names the source page `[[roam/agent guidelines]]`. It also distinguishes itself from the sibling `roam_markdown_cheatsheet` by stating what each is for, eliminating 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?
Explicitly instructs 'Call this ONCE per graph per session, before other tools, INCLUDING for reads' and contrasts with the alternative: 'Call that when you need to look something up; this one you need before writing at all.' This gives clear when-to-use and when-not-to-use guidance with a direct sibling reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explicitly discloses that 'This REPLACES the page' and any unaccounted block is deleted. It explains the smart diff algorithm step-by-step, mentions hidden subtrees are excluded and left untouched, and that `preserved_hidden` reports the count. It also notes the requirement to call guidelines once per session, offering deep behavioral insight beyond the structured 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?
Despite being long, the description is well-structured with clear sections: summary, use cases, warning, how-it-works steps, hidden subtree note, and important prerequisite. Every sentence adds critical information, and the formatting (bullets, bold warning, numbered list) makes it scannable. It is appropriately detailed for a complex, destructive tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is exceptionally complete given the tool's complexity. It covers purpose, alternatives, destructive behavior, algorithm steps, hidden content handling, output hints, and required prior steps. Combined with rich schema and annotations, the agent has all necessary context to select and invoke the tool safely.
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 baseline is 3. The description adds some context around `dry_run` usage and mentions `preserved_hidden` (an output field), but does not provide additional meaning for the parameters beyond what the schema already documents. It reinforces the purpose but does not elevate semantic understanding.
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 'Updates an existing page with new markdown content using smart diff' and lists specific use cases. It distinguishes itself from siblings by explicitly naming alternatives like `roam_process_batch_actions` and `roam_create_outline` for partial edits.
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 the tool ('ideal for syncing...', 'AI-assisted content updates...') and when not to, warning that it replaces the whole page and directing to alternatives for partial changes. It also instructs to use `dry_run: true` and to call `roam_get_guidelines` first, covering prerequisites and exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring read-only/idempotent, the description adds meaningful behavioral details: it explains that the trailing slash is added automatically, that filter_tag matches both #tag and [[tag]] usage, and that include_content controls whether full block content is returned. The IMPORTANT note about conventions affecting how results are read adds extra context beyond the 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 three sentences plus a focused IMPORTANT note. It front-loads the core purpose, uses no filler, and each sentence adds a distinct piece of information.
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?
The description covers the tool's behavior, prerequisites, and optional parameters. Since there is no output schema, it would be helpful to state the exact return shape, but the description implies a list of sub-pages and mentions content inclusion for include_content. Overall it's sufficiently complete for a read-only list tool.
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 covers all 5 parameters with detailed descriptions, so the baseline is 3. The description enhances the meaning of 'prefix' by explaining the namespace/title-prefix matching convention and the hierarchy section, which aids correct parameter use.
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 opens with 'Fetch all sub-pages (namespace children) of a given page prefix,' which is a specific verb+resource. It further distinguishes itself from roam_search_hierarchy (block parent/child traversal) and clarifies the title-prefix matching rule.
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?
Explicitly names an alternative tool: 'distinct from roam_search_hierarchy which traverses block parent/child relationships.' It also mandates a prerequisite: 'call roam_get_guidelines for this graph once per session before using this tool,' including for reads.
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:

[![roam-research-mcp MCP server](https://glama.ai/mcp/servers/2b3pro/roam-research-mcp/badges/card.svg)](https://glama.ai/mcp/servers/2b3pro/roam-research-mcp)

Score Badge

Copy to your README.md:

[![roam-research-mcp MCP server](https://glama.ai/mcp/servers/2b3pro/roam-research-mcp/badges/score.svg)](https://glama.ai/mcp/servers/2b3pro/roam-research-mcp)

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/2b3pro/roam-research-mcp'

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