Server Quality Checklist

Tool Scores

• edit_paragraph_textC
  2.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Edit' implies mutation, the description doesn't specify whether this operation is reversible, what permissions are required, whether it overwrites or merges content, or what happens to formatting. For a mutation tool with zero annotation coverage, this is a significant gap.

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

  Conciseness4/5

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

  The description is appropriately concise with a clear purpose statement followed by parameter documentation. The structure is logical and front-loaded, though the parameter documentation could be more integrated rather than appearing as a separate 'Args' section.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given this is a mutation tool with no annotations, 3 parameters at 0% schema coverage, but with an output schema present, the description is minimally adequate. The output schema existence means return values don't need explanation, but the description should do more to explain parameter semantics and behavioral implications of editing paragraph text.

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

  Parameters2/5

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

  With 0% schema description coverage and 3 parameters, the description must compensate but provides only basic parameter names without explaining their semantics. It doesn't clarify what format 'file_path' expects, what constitutes a valid 'node_id', or whether 'new_text' supports formatting. The description adds minimal value beyond what the bare schema provides.

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

  Purpose3/5

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

  The description states the tool 'Edit paragraph text content', which is a clear verb+resource combination. However, it doesn't distinguish this from sibling tools like 'edit_node_attributes' or 'edit_summary', leaving ambiguity about when to use this specific paragraph editing tool versus other editing tools in the server.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'edit_node_attributes' and 'edit_summary' available, there's no indication whether this is for basic text replacement versus more complex editing scenarios, or any prerequisites for using this tool.

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

• move_nodesC
  2.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. While 'move' implies mutation, it doesn't disclose critical behavioral traits: whether this operation requires specific permissions, what happens to node positions in the new parent, whether the move is atomic or can fail partially, or how it affects references to moved nodes. The description is minimal and lacks necessary context for safe use.

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

  Conciseness3/5

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

  The description is brief and front-loaded with the core purpose, but the parameter explanations are minimal and don't add significant value. While not verbose, the under-specification means it could be more informative without losing conciseness. The structure is clear but could be improved with more substantive content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the complexity of a mutation tool with 3 parameters, 0% schema description coverage, no annotations, and sibling tools that suggest a rich node-manipulation context, the description is incomplete. It doesn't address prerequisites, error conditions, or the impact of the operation. The presence of an output schema helps, but the description should provide more context for safe and effective use.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It lists the three parameters with brief explanations, but these add minimal semantic value beyond the schema's names. For example, it doesn't explain what format 'node_ids' expects (e.g., strings, integers), what 'new_parent_id' represents, or how 'file_path' relates to the HNPX document structure. The description fails to adequately compensate for the lack of schema descriptions.

  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 action ('move multiple nodes') and the resource ('between parents'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'reorder_children' or 'remove_nodes', which might involve similar node manipulation operations.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. With siblings like 'reorder_children' (which might change order within a parent) and 'remove_nodes' (which might delete nodes), there's no indication of when moving nodes between parents is the appropriate choice versus other operations.

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

• create_beatC
  2.8/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Create' implies a write/mutation operation, the description doesn't address important behavioral aspects like: what permissions are required, whether the creation is reversible, what happens if the parent_id doesn't exist, or what the tool returns (though an output schema exists). The description is minimal and lacks 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 is appropriately concise with a clear two-part structure: a purpose statement followed by parameter descriptions. Every sentence serves a purpose, though the parameter descriptions could be more informative. The information is front-loaded with the main action first.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given that this is a creation/mutation tool with no annotations, 3 parameters with 0% schema coverage, but with an output schema present, the description is moderately complete. The presence of an output schema means the description doesn't need to explain return values, but it should do more to explain the tool's behavior, parameter expectations, and differentiation from sibling tools.

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

  Parameters2/5

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

  The schema description coverage is 0%, so the schema provides no parameter documentation. The description includes an 'Args' section that names and briefly describes each parameter, which adds value beyond the bare schema. However, the descriptions are minimal ('Path to the HNPX document', 'ID of the parent sequence element', 'Beat summary text') and don't explain format expectations, constraints, or examples.

  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 action ('Create') and resource ('new beat element'), which is specific and unambiguous. However, it doesn't differentiate this tool from sibling tools like 'create_chapter', 'create_paragraph', or 'create_sequence', which all appear to create different types of elements in the same document system.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'create_chapter' or 'create_paragraph'. It mentions that a beat is created within a parent sequence element, but doesn't explain what distinguishes a 'beat' from other element types or when this specific creation tool is appropriate.

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

• edit_node_attributesC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden but lacks behavioral details. It mentions modifying attributes but doesn't disclose critical traits like whether changes are destructive, require specific permissions, have rate limits, or what happens on error (e.g., invalid node_id). The description is minimal, offering little beyond the basic action, which is insufficient for a mutation tool with zero annotation coverage.

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

  Conciseness4/5

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

  The description is appropriately sized and front-loaded, with the purpose stated clearly in the first sentence. The Args section is structured but could be more integrated; overall, it avoids unnecessary verbosity. However, the separation into 'Args' feels slightly disjointed, and every sentence adds value without waste.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity (mutation with 3 parameters, nested objects, and an output schema), the description is minimally adequate. The output schema existence means return values needn't be explained, but the description lacks context on HNPX documents, attribute types, or error handling. With no annotations and low schema coverage, it should do more to be complete, but it meets a basic threshold by stating the action and parameters.

  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 0%, so the description must compensate but only partially does. It lists parameters (file_path, node_id, attributes) and briefly explains attributes as a dictionary of names and values to update, adding some meaning beyond the schema's type definitions. However, it doesn't detail parameter formats (e.g., what node_id looks like, valid attribute names), leaving gaps. With 0% coverage, this is a baseline effort that doesn't fully address the deficiency.

  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 action ('Modify attributes') and target ('existing node'), distinguishing it from creation tools (e.g., create_beat, create_chapter) and other edit tools (e.g., edit_paragraph_text). However, it doesn't specify what types of attributes can be modified or the node's context (e.g., HNPX document structure), leaving some ambiguity compared to siblings like edit_summary.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this tool versus alternatives is provided. For instance, it doesn't clarify when to choose edit_node_attributes over edit_paragraph_text for text changes or how it differs from move_nodes for structural modifications. The description only implies usage by stating it modifies attributes of an existing node, without context or exclusions.

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

• edit_summaryC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action is to 'Edit,' implying a mutation operation, but fails to describe critical behaviors such as permission requirements, whether the edit is reversible, error handling, or side effects. This is a significant gap for a mutation tool with zero annotation coverage.

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

  Conciseness4/5

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

  The description is appropriately sized and front-loaded, with the core purpose stated first in a concise sentence, followed by parameter details. There is no wasted text, and the structure is clear, though the parameter descriptions could be more informative without sacrificing brevity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's complexity as a mutation operation with no annotations, 3 parameters, and an output schema present, the description is partially complete. It covers the basic purpose and parameters but lacks behavioral details and usage guidelines. The output schema mitigates the need to explain return values, but overall completeness is moderate with clear 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?

  The description includes an 'Args' section that lists and briefly describes each parameter, adding meaning beyond the input schema, which has 0% description coverage. However, the descriptions are minimal (e.g., 'Path to the HNPX document') and do not provide detailed semantics like format constraints or examples, offering only basic compensation for the schema gap.

  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 action ('Edit') and target ('summary text of a node'), making the purpose evident. However, it does not explicitly differentiate this tool from similar siblings like 'edit_node_attributes' or 'edit_paragraph_text', which might also modify node content or properties, leaving some ambiguity in sibling distinction.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. With siblings like 'edit_node_attributes' and 'edit_paragraph_text' available, there is no indication of specific contexts, prerequisites, or exclusions for choosing 'edit_summary' over other editing tools, leaving usage unclear.

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

• remove_node_childrenC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Remove all children') which implies a destructive mutation, but doesn't specify whether this is reversible, what permissions are required, what happens to the children (deleted vs orphaned), or any rate limits. The description is minimal and lacks important behavioral context for a destructive operation.

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

  Conciseness4/5

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

  The description is appropriately concise with a clear purpose statement followed by parameter explanations. The two-sentence structure is efficient with no wasted words. However, the parameter explanations could be integrated more naturally rather than as a separate 'Args:' section.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given this is a destructive mutation tool with no annotations, 0% schema description coverage, but with an output schema (which handles return values), the description is minimally adequate. It covers the basic action and parameters but lacks important context about the mutation's behavior, safety considerations, and relationship to sibling tools. The presence of an output schema prevents this from being a complete failure.

  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 0%, so the schema provides no parameter documentation. The description adds basic semantics for both parameters ('Path to the HNPX document' and 'ID of the parent node'), establishing their roles. However, it doesn't explain format expectations (e.g., what constitutes a valid node_id, file path conventions) or provide examples, leaving significant gaps.

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

  Purpose4/5

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

  The description clearly states the verb ('Remove') and resource ('all children of a node'), making the purpose specific and understandable. It distinguishes from sibling 'remove_nodes' which likely removes nodes themselves rather than just their children. However, it doesn't explicitly mention the HNPX document format context beyond the parameter description.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'remove_nodes' or 'reorder_children'. There's no mention of prerequisites, consequences, or typical scenarios for removing children versus other operations. The agent must infer usage from the name alone.

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

• reorder_childrenC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It implies a mutation ('reorganize') but doesn't disclose behavioral traits like whether changes are permanent, if it requires specific permissions, error conditions (e.g., invalid IDs), or side effects. The description lacks context on what 'reorganize' entails operationally beyond the basic action.

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

  Conciseness4/5

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

  The description is appropriately sized and front-loaded with the core purpose in the first sentence. The 'Args' section is structured but could be more integrated; overall, it's efficient with minimal waste, though slightly fragmented between the summary and parameter list.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given 3 parameters with 0% schema coverage, no annotations, but an output schema exists, the description is moderately complete. It covers the basic action and parameters but lacks behavioral context, usage guidelines, and detailed parameter semantics. The output schema mitigates the need to explain return values, but gaps remain in mutation handling and tool selection.

  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 0%, so the description must compensate. It adds meaning by explaining each parameter's purpose (e.g., 'parent_id' identifies the parent node, 'child_ids' is the desired order list), which clarifies beyond the bare schema types. However, it doesn't provide format details (e.g., ID formats, path syntax) or constraints, leaving gaps in parameter understanding.

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

  Purpose4/5

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

  The description clearly states the verb ('reorganize') and resource ('child elements'), specifying it's about ordering. It distinguishes from siblings like 'move_nodes' (which likely moves nodes between parents) and 'remove_node_children' (which removes children). However, it doesn't explicitly mention the HNPX document context or contrast with all siblings like 'edit_node_attributes'.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing existing parent/children), exclusions (e.g., not for reordering across parents), or comparisons to siblings like 'move_nodes' for different reordering scenarios. The description only states what it does, not when to choose it.

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

• create_sequenceB
  3/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permissions needed, whether it's idempotent, what happens on failure, or what the output contains. The description adds minimal behavioral context beyond the basic 'create' action.

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

  Conciseness3/5

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

  The description is appropriately sized but not optimally structured. The purpose statement is clear but brief, and the parameter documentation is comprehensive but presented as a simple list without prioritization or grouping of required vs optional parameters.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given a creation tool with 6 parameters, 0% schema coverage, no annotations, but with an output schema present, the description is moderately complete. It documents all parameters well but lacks behavioral context and usage guidance. The presence of an output schema means the description doesn't need to explain return values.

  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?

  With 0% schema description coverage for 6 parameters, the description compensates well by documenting all parameters with clear explanations. It adds meaning beyond the schema by explaining what each parameter represents (e.g., 'Path to the HNPX document', 'ID of the parent chapter element', 'Time indicator (e.g., "night", "next day", "flashback")').

  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 creates a 'new sequence element' with a specific verb+resource combination. It distinguishes from siblings like 'create_chapter' or 'create_paragraph' by specifying it creates a 'sequence' element, though it doesn't explicitly contrast with all sibling creation tools.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'create_chapter' or 'create_beat'. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage from parameter names alone.

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

• create_paragraphB
  3.1/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't address permissions, whether it modifies the document in-place, error handling, or what happens if parent_id is invalid. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.

  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 efficiently structured with a clear purpose statement followed by parameter explanations. Each sentence adds value, though the parameter explanations could be slightly more integrated with the main description rather than appearing as a separate 'Args' section.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given this is a mutation tool with no annotations but with an output schema (which handles return values), the description covers parameters well but lacks behavioral context about the creation operation's effects, error conditions, and relationship to sibling tools. It's minimally adequate but has clear 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?

  With 0% schema description coverage, the description compensates well by explaining all 5 parameters: file_path identifies the document, parent_id specifies location, text provides content, mode defines narrative type with enum values, and char clarifies conditional requirement. 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.

  Purpose4/5

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

  The description clearly states the action ('Create a new paragraph element') and identifies the resource ('paragraph element'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'edit_paragraph_text' or 'create_beat', which would require a more specific comparison.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'edit_paragraph_text' for modifying existing paragraphs or 'create_beat' for other element types. It mentions parameter dependencies (char required for dialogue mode) but offers no broader contextual advice for tool selection.

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

• create_chapterB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Create' which implies a write/mutation operation, but doesn't address permissions, side effects, error handling, or what the output looks like. This is a significant gap for a mutation tool with zero annotation coverage.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded with the core purpose, followed by a concise parameter list. Every sentence earns its place, with no redundant or verbose language, making it efficient and easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given that this is a mutation tool with no annotations, 5 parameters (4 required), and an output schema exists, the description is moderately complete. It covers parameter semantics well but lacks behavioral context and usage guidelines. The output schema mitigates the need to describe return values, but overall gaps remain.

  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 0%, so the description must compensate. It provides clear semantics for all 5 parameters (e.g., 'Path to the HNPX document' for file_path, 'ID of the parent book element' for parent_id), adding meaningful context beyond the bare schema. However, it doesn't specify format constraints or examples, keeping it from a perfect score.

  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 action ('Create a new chapter element') and resource ('chapter'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'create_paragraph' or 'create_sequence' beyond the chapter focus, so it doesn't reach the highest level of sibling differentiation.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'create_paragraph' or 'create_sequence', nor does it mention prerequisites or context. It simply states what the tool does without indicating appropriate scenarios or exclusions.

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

• create_documentB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It states it 'creates' a new document, implying a write/mutation operation, but doesn't disclose behavioral traits such as permissions required, whether it overwrites existing files, error handling (e.g., invalid paths), or what 'empty' entails (e.g., default structure). This leaves significant gaps for a mutation tool.

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

  Conciseness5/5

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

  The description is appropriately sized and front-loaded: the first sentence states the core purpose, and the Args section efficiently documents the parameter. There is no wasted text, and every sentence adds value (defining the tool and its parameter).

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given complexity (a mutation tool with 1 parameter, 0% schema coverage, no annotations, but has output schema), the description is minimally adequate. It covers the basic action and parameter, but lacks behavioral details (e.g., side effects, error cases) and doesn't leverage the output schema to explain return values. For a creation tool, more context on outcomes would be helpful.

  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 0%, so the description must compensate. It adds meaning by explaining that 'file_path' is where the new document 'will be created,' clarifying its purpose beyond the schema's type/requirement. However, it doesn't specify format (e.g., file extension like .hnpx) or constraints (e.g., absolute vs. relative paths), leaving some ambiguity.

  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 action ('Create a new empty HNPX document') and specifies the resource type (HNPX document). It distinguishes from siblings like create_beat, create_chapter, etc., by specifying it creates an 'empty document' rather than content elements. However, it doesn't explicitly differentiate from all siblings (e.g., edit_node_attributes could also create nodes).

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid file path), exclusions (e.g., not for editing existing documents), or comparisons to siblings like create_paragraph (for content within documents) or get_empty (which might retrieve empty documents).

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

• render_nodeB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It mentions the tool renders 'only descendent paragraphs' and describes output formatting options, but lacks critical behavioral details: whether it requires file access permissions, if it modifies the document, error handling, or performance characteristics. For a tool with 4 parameters and no annotations, this is insufficient.

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

  Conciseness5/5

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

  The description is efficiently structured: a clear purpose statement, followed by labeled sections for Args and Returns. Every sentence adds value—no redundancy or fluff. The formatting makes it easy to scan and understand quickly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given 4 parameters with 0% schema coverage and no annotations, the description does well on parameters but lacks behavioral context. The output schema exists (returns 'str'), so describing return values isn't needed. However, for a tool interacting with document files and nodes, more on permissions, side effects, or error cases would improve completeness.

  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 0%, so the description must compensate. It explains all 4 parameters: 'file_path' and 'node_id' as required inputs, and clarifies 'show_ids' and 'show_markers' as boolean flags controlling output formatting. This adds meaningful context beyond the bare schema types, though it doesn't detail path formats or ID structures.

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

  Purpose4/5

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

  The description clearly states the verb ('Render') and resource ('text representation of the node'), specifying it only includes 'descendent paragraphs'. It distinguishes from siblings like 'get_node' or 'get_subtree' by focusing on formatted text output rather than raw data. However, it doesn't explicitly contrast with all similar siblings.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives like 'get_subtree' or 'get_node' is provided. The description implies it's for formatted text output but doesn't specify scenarios where this is preferable over other retrieval tools. No prerequisites or exclusions are mentioned.

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

• get_root_idB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It mentions the tool 'Get[s] ID' which implies a read operation, but doesn't disclose any behavioral traits like whether it requires specific file permissions, what happens with invalid paths, if it caches results, or error handling. For a tool with no annotation coverage, this is insufficient disclosure.

  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 perfectly concise and well-structured: a clear purpose statement followed by Args and Returns sections. Every sentence earns its place with no wasted words. The information is front-loaded with the core purpose first.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's simple nature (single parameter, read-only operation), the description combined with the output schema provides adequate context. The output schema handles return value documentation, so the description doesn't need to explain returns. However, for a tool with no annotations, more behavioral context would be beneficial.

  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?

  With 0% schema description coverage, the description must compensate, and it does by explaining the single parameter: 'file_path (str): Path to the HNPX document'. This adds crucial meaning beyond the bare schema. However, it doesn't specify path format requirements or examples, so it's not a perfect 5.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get ID of the book node (document root)' with a specific verb ('Get') and resource ('book node ID'). It distinguishes from siblings like get_node or get_path by specifying it retrieves the root ID specifically. However, it doesn't explicitly contrast with all siblings, so it's not a perfect 5.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. Given siblings like get_node, get_path, and get_subtree that also retrieve node information, there's no indication of when this specific root ID retrieval is preferred. The description only states what it does, not when to use it.

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

• get_childrenA
  3.5/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data (implying read-only, non-destructive) and specifies the return format ('Concatenated XML representation'), which is useful context. However, it doesn't cover error handling, permissions, or rate limits, leaving gaps for a tool with no annotation support.

  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 front-loaded with the core purpose in the first sentence, followed by structured sections for Args and Returns. Each sentence earns its place by providing essential information without redundancy, making it highly efficient and well-organized.

  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 (2 parameters, no annotations, but with an output schema), the description is mostly complete. It explains the purpose, parameters, and return format. Since an output schema exists, it doesn't need to detail return values further. However, it lacks usage guidelines and some behavioral context, preventing a perfect score.

  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 0%, so the description must compensate. It adds meaning by explaining that 'file_path' refers to 'Path to the HNPX document' and 'node_id' is the 'ID of the parent node', clarifying the parameters' roles beyond their names. However, it doesn't detail format constraints (e.g., HNPX structure, ID syntax), so it's not a full 5.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Retrieve immediate child nodes of a specified parent'. It specifies the verb ('Retrieve') and resource ('immediate child nodes'), and distinguishes it from siblings like 'get_subtree' (which retrieves deeper descendants) and 'get_node' (which retrieves a single node). However, it doesn't explicitly contrast with all siblings, so it's not a perfect 5.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose 'get_children' over 'get_subtree' (for deeper descendants) or 'get_node' (for the parent itself), nor does it specify prerequisites or exclusions. The agent must infer usage from the purpose alone.

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

• remove_nodesA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is 'permanent' and removes 'descendants', which is valuable. However, it omits critical details: whether this requires specific permissions, what happens on failure (e.g., partial removal), if changes are reversible, or any rate limits. For a destructive operation, this is a significant gap.

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

  Conciseness5/5

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

  The description is highly efficient: a single sentence states the purpose, followed by a clear 'Args:' section listing parameters with brief explanations. Every element earns its place—no redundancy or fluff. It's front-loaded with the core action and structured for quick parsing.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given a destructive tool with no annotations, 0% schema coverage, but an output schema (which handles return values), the description is partially complete. It covers the purpose and parameters well but lacks behavioral context (e.g., safety, error handling) and usage guidelines. For a high-stakes operation like permanent removal, more guidance is warranted despite the output schema.

  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 0%, so the description must compensate. It explicitly documents both parameters: 'file_path' as a path to an HNPX document and 'node_ids' as a list of node IDs to remove. This adds essential meaning beyond the bare schema, though it could specify format details (e.g., ID types or path syntax). With 0% coverage and 2 parameters, this is strong but not exhaustive.

  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 ('permanently remove'), the resource ('multiple nodes and all their descendants'), and distinguishes from siblings like 'remove_node_children' (which only removes children) and 'move_nodes' (which relocates rather than deletes). The verb+resource combination is precise and unambiguous.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'remove_node_children' (for partial removal) or 'edit_node_attributes' (for modification instead of deletion). It lacks context about prerequisites (e.g., whether nodes must exist) or exclusions (e.g., not for single-node removal if a simpler tool exists).

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

• get_pathA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses the return type (concatenated XML representation) and the path scope (from root to target), but lacks details on error handling, performance, or side effects. It adequately describes the core behavior without contradictions.

  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 front-loaded with the core purpose, followed by structured Args and Returns sections. Every sentence adds value, with no wasted words, making it efficient and easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's moderate complexity (2 parameters, no annotations), the description is mostly complete: it explains purpose, parameters, and return value. However, it lacks guidance on usage versus siblings and behavioral details like error cases. The presence of an output schema (Returns: str) reduces the need for return value explanation.

  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 explaining both parameters: file_path as 'Path to the HNPX document' and node_id as 'ID of the target node'. This adds essential meaning beyond the bare schema types.

  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 a specific verb ('Return') and resource ('hierarchical path from document root to specified node'), and it distinguishes from siblings like get_node, get_subtree, get_children, and get_root_id by specifying it returns a concatenated path rather than a single node or subtree.

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

  Usage Guidelines3/5

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

  The description implies usage when needing a hierarchical path to a node, but does not explicitly state when to use this tool versus alternatives like get_node (for a single node) or get_subtree (for a subtree). No exclusions or prerequisites are mentioned.

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

• get_subtreeA
  4.1/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden. It mentions the tool retrieves XML representation with pruning, but doesn't disclose important behavioral aspects like whether this is a read-only operation (implied but not stated), error conditions, performance characteristics, or what happens with invalid node IDs. For a tool with 3 parameters and no annotation coverage, this is insufficient.

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

  Conciseness5/5

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

  Perfectly structured with a clear purpose statement followed by Args and Returns sections. Every sentence earns its place - the first sentence establishes core functionality, the Args section documents all parameters with their types and constraints, and the Returns section specifies output format. Zero waste.

  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 (3 parameters, XML output, pruning logic) and having an output schema, the description is mostly complete. It explains parameters well and specifies the return format. However, for a tree traversal tool with no annotations, it could benefit from mentioning read-only nature, error handling, or performance considerations for deep trees.

  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 clearly explaining all 3 parameters: file_path (path to HNPX document), node_id (ID of node to retrieve), and pruning_level (depth level with specific enum values). The Returns section also clarifies the output. 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 ('Retrieve XML representation'), target resource ('node including all descendants'), and distinguishes from siblings like get_node (which presumably doesn't include descendants) and get_children (which might only get immediate children). The mention of 'optionally pruned' adds important scope information.

  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 when to use this tool (when you need a node's full subtree in XML format with pruning options) but doesn't explicitly contrast with alternatives like get_node or get_children. It provides context about what the tool does but lacks explicit 'when not to use' guidance or named alternatives.

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

• get_emptyA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries full burden. It discloses the search algorithm (BFS order) and return behavior (XML representation or message if none found), which are valuable behavioral traits. However, it doesn't mention error handling, performance characteristics, or what constitutes a 'container node' versus other node types.

  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 perfectly structured with a clear purpose statement followed by Args and Returns sections. Every sentence earns its place: the first sentence explains what the tool does, the Args section clarifies parameters, and the Returns section specifies output. 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 2 parameters with 0% schema coverage and an output schema exists (Returns section), the description provides good coverage. It explains the tool's purpose, parameters, and return values adequately. However, for a tree traversal tool, it could benefit from mentioning edge cases (e.g., invalid node_id, empty document) or performance notes.

  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 0%, so the description must compensate. It explains that file_path is 'Path to the HNPX document' and node_id is 'ID of the node to search within', adding essential meaning beyond the bare schema. However, it doesn't specify format requirements (e.g., HNPX file structure, node ID format) or constraints.

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

  Purpose5/5

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

  The description clearly states the specific action ('Find next container node without children'), the resource ('within a specific node's subtree'), and the algorithm ('BFS order'). It distinguishes from siblings like get_children, get_subtree, and get_node by specifying the search for empty containers rather than general retrieval.

  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 for finding empty containers in a subtree, but doesn't explicitly state when to use this tool versus alternatives like get_children (which retrieves all children) or get_subtree (which retrieves entire subtree). It provides clear context but lacks explicit exclusions or named alternatives.

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

• get_nodeA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the core behavior (retrieves XML representation of a specific node without descendants) and specifies what is included in the return (attributes and summary child only). However, it lacks details on potential errors (e.g., invalid file_path or node_id), performance aspects, or any side effects, which are important for a read operation in a document system.

  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 in the first sentence, followed by clear sections for Args and Returns. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

  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 (a read operation with 2 parameters), no annotations, and an output schema present (which handles return values), the description is largely complete. It covers purpose, parameters, and return scope adequately. However, it could benefit from more behavioral context (e.g., error handling or performance notes) to fully compensate for the lack of annotations.

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

  Parameters4/5

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

  The schema description coverage is 0%, so the description must compensate. It adds meaningful semantics by explaining that file_path is 'Path to the HNPX document' and node_id is 'ID of the node to retrieve', which clarifies the purpose of each parameter beyond their names. However, it does not provide format details (e.g., expected path format or ID structure), leaving some ambiguity.

  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 ('Retrieve XML representation') and resource ('a specific node'), explicitly distinguishes it from siblings by specifying 'without descendants' (unlike get_subtree or get_children), and clarifies the scope of what is returned (node with attributes and summary child only).

  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 for when to use this tool (to retrieve a single node's XML without descendants), but does not explicitly mention when not to use it or name specific alternatives (e.g., get_subtree for nodes with descendants, get_children for child nodes). However, the distinction from siblings is implied through the 'without descendants' clause.

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