Server Quality Checklist

Tool Scores

• write_to_pageA
  4.5/5.0
  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 and does so effectively. It explains that content is appended to the end of the page, describes automatic indentation detection, maintains parent-child relationships, and specifies that the page must already exist (case-sensitive). It also provides return format details, though an output schema exists.

  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, args, returns, examples) and front-loads the core functionality. While comprehensive, some sentences could be more concise, and the formatting example within the content parameter description is slightly verbose but still informative.

  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 (hierarchical content creation), no annotations, and 0% schema coverage, the description provides complete context. It covers purpose, usage, parameters, return values (even with output schema), and includes practical examples. The description fully compensates for the lack of structured metadata.

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

  Parameters5/5

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

  With 0% schema description coverage, the description fully compensates by providing detailed parameter semantics. It explains that page_name must be exact and case-sensitive, that content uses hierarchical markdown with '- ' prefix and indentation, provides specific formatting examples, and describes automatic indentation detection. This adds substantial value beyond the bare 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 clearly states the specific action ('write hierarchical markdown content'), target resource ('specific page in Roam Research'), and distinguishes from siblings by focusing on content creation rather than retrieval (get_page_content, get_page_references) or date-specific writing (write_to_today). It provides a complete verb+resource+scope statement in the first sentence.

  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 (writing hierarchical content to existing pages) and implicitly distinguishes from siblings through its focus on content creation. However, it doesn't explicitly state when NOT to use it or name specific alternatives for different scenarios beyond the sibling tool names provided separately.

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

• get_page_contentA
  4.6/5.0
  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 traits: it's a read operation (implied by 'Get'), specifies depth limits ('up to 5 levels deep'), output format ('markdown format with proper indentation'), and includes examples. It lacks details on error handling or rate limits, but covers essential behavior for a retrieval tool.

  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 purpose, followed by details on behavior, parameters, returns, and examples. Each sentence adds value without redundancy, making it efficient and easy for an agent to parse.

  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 (1 parameter, no annotations, but with output schema), the description is complete. It covers purpose, usage context, behavioral traits, parameter semantics, and includes examples. The output schema handles return values, so the description appropriately focuses on other aspects without redundancy.

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

  Parameters5/5

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

  The schema has 0% description coverage, so the description must fully compensate. It adds significant meaning beyond the schema by explaining the parameter 'page_name' as 'Exact name of the page to retrieve (case-sensitive)', providing clarity on format and constraints that the schema alone does not include.

  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 ('Get the complete content'), resource ('a specific page in Roam Research'), and scope ('with all nested child blocks'). It distinguishes from siblings like 'get_page_references' (which likely gets references rather than content), 'write_to_page' (which modifies rather than retrieves), and 'write_to_today' (which writes to a specific page).

  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 implies usage by specifying the tool retrieves content from a page, which contrasts with writing tools ('write_to_page', 'write_to_today') and a references tool ('get_page_references'). However, it does not explicitly state when to use this tool versus alternatives or provide exclusions, leaving some ambiguity for the agent.

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

• get_page_referencesA
  4.6/5.0
  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: pagination mechanism (cursor-based), sorting (by most recent edit time), inclusion of hierarchical context, and the JSON return structure. It doesn't mention rate limits, authentication needs, or error conditions, but covers the core operational behavior well.

  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 purpose. Every sentence adds value: explains what it finds, how results are sorted, parameter details, return format, and examples. No wasted words while maintaining clarity.

  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 (pagination, hierarchical context), no annotations, and the presence of an output schema, the description provides excellent completeness. It explains the pagination mechanism, sorting behavior, return structure, and includes practical examples. The output schema handles return value details, so the description appropriately focuses on operational context.

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

  Parameters5/5

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

  The schema description coverage is 0%, so the description must fully compensate. It provides excellent parameter semantics: explains page_name is case-sensitive, limit is maximum per request with default, and cursor is for pagination with specific usage instructions. This adds substantial meaning beyond the bare schema.

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

  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 ('Get all blocks that reference a specific page'), resource ('Roam Research'), and scope ('with pagination support'). It distinguishes this from siblings like get_page_content (which retrieves page content rather than references) and write tools by focusing on reference discovery.

  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 (finding blocks that link to a specific page) and implies usage through examples. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings, though the purpose differentiation is strong enough to guide selection.

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

• write_to_todayA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it automatically creates the page if missing, uses Roam's standard date format, maintains block relationships, and describes the return structure. It doesn't mention error conditions, rate limits, or authentication requirements, 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.

  Conciseness5/5

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

  The description is well-structured with clear sections (purpose, behavior, args, returns, examples) and every sentence adds value. It's appropriately sized for a tool with one parameter but complex behavior, with no redundant information.

  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 (automatic page creation, hierarchical content processing) and the presence of an output schema, the description provides excellent context. It explains the tool's behavior, parameter requirements, return structure, and includes practical examples, making it complete enough for effective use despite having no annotations.

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

  Parameters5/5

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

  The schema has 0% description coverage for its single parameter, but the description comprehensively explains the 'content' parameter with format details, examples, and hierarchical structure requirements. It adds significant value beyond the bare schema by specifying the markdown format, indentation rules, and providing concrete examples.

  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 ('write hierarchical markdown content', 'automatically creates today's daily page') and identifies the target resource ('today's daily page in Roam Research'). It distinguishes from sibling tools like 'write_to_page' by specifying the date-specific nature of this operation.

  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 (for writing to today's daily page in Roam Research) and implicitly distinguishes it from 'write_to_page' which likely writes to arbitrary pages. However, it doesn't explicitly state when NOT to use this tool or mention alternatives like 'get_page_content' for reading operations.

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