Server Quality Checklist

Tool Scores

• hedgedoc_readA
  3.5/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It states the tool reads content but does not explicitly confirm it is non-destructive, does not mention error handling (e.g., if the note does not exist), or any auth/rate-limit considerations. The name suggests read-only, but the description adds no insight beyond that.

  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: one sentence stating the core purpose and one bullet defining the parameter. No unnecessary words or redundancy. It is front-loaded and to the point.

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

  Completeness3/5

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

  For a simple read tool with one parameter, the description is minimally adequate: it states the purpose and explains the parameter. However, it lacks usage guidance and behavioral detail. The presence of an output schema covers return format, but the description itself is incomplete for an agent that must decide between this and siblings. Given the low complexity, this is acceptable but leaves 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?

  The description includes a clear explanation of the sole parameter: 'note_id: The note ID or alias (the slug from the URL)'. This adds practical meaning beyond the schema's bare 'Note Id' title, explaining the format and that aliases are accepted. Since schema description coverage is 0%, this fills the gap 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 uses a clear verb ('Read') and specifies the resource ('a HedgeDoc note') and the exact output ('raw markdown content'). This distinguishes it from sibling tools like hedgedoc_info (which likely returns metadata) and hedgedoc_slide_url (which generates links).

  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 gives no explicit guidance on when to use this tool versus alternatives. It does not mention that hedgedoc_info might be better for metadata or that hedgedoc_get_revision is for historical content. Usage context is only implied by the phrase 'Read the raw markdown content.'

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

• hedgedoc_infoA
  3.7/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, but it does not disclose whether the operation is read-only, side effects, error conditions, or any other behavioral context. It only says 'Get metadata' without stating that no modifications occur.

  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 exceptionally concise, with a single sentence and a bullet point. Every piece of content is relevant and front-loaded, with no filler or redundancy.

  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?

  The tool is simple and has an output schema, so return values are covered. However, the description lacks usage guidance and behavioral transparency, leaving some context gaps despite the low complexity.

  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 only lists note_id as a string with no description. The tool description compensates by explaining that note_id is 'the note ID or alias (the slug from the URL)', adding crucial semantic meaning beyond 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 states 'Get metadata of a HedgeDoc note' and enumerates specific fields (title, description, timestamps, viewcount), making the tool's purpose distinct from sibling tools like hedgedoc_read or hedgedoc_create.

  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?

  Usage context is only implied by the tool name and the phrase 'Get metadata'. No explicit guidance on when to use this tool versus alternatives, nor any exclusions, is provided.

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

• hedgedoc_get_revisionA
  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 must carry the burden of behavioral disclosure. It does state that the tool returns JSON with note content and authorship data, which gives some insight into the output. However, it does not mention read-only status, error conditions, authentication requirements, or side effects, leaving gaps for a tool with zero 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 concise and well-structured. The opening sentence states the purpose, followed by a bullet list clarifying the two parameters, and a final line about the return format. Every sentence adds value with no redundant filler.

  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 tool has only two required parameters and an output schema is available. The description explains the purpose, parameters, and return type ('Returns JSON with the note content and authorship data'), which is sufficient for a simple read operation. It could be more complete by mentioning potential errors or when to use it relative to hedgedoc_read, but it covers the essentials.

  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 input schema has 0% description coverage, but the description fully compensates by explaining both parameters: note_id is 'the note ID or alias (the slug from the URL)' and revision_id is 'the revision ID (Unix timestamp from hedgedoc_list_revisions)'. This adds significant meaning beyond the bare schema fields and provides practical guidance on where to obtain the values.

  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 'Get the full content and authorship of a specific revision' with a specific verb and resource. It distinguishes itself from sibling tools like hedgedoc_list_revisions (which lists revisions) and hedgedoc_read (which likely gets current content) by focusing on a specific revision.

  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 context by noting that revision_id is a Unix timestamp from hedgedoc_list_revisions, which cross-references a sibling tool. However, it does not explicitly state when to use this tool versus hedgedoc_read or hedgedoc_list_revisions, nor does it provide any exclusions or alternative suggestions.

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

• hedgedoc_statusA
  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 must disclose behavior. It reveals that the tool returns JSON with specific metrics and hints at read-only nature via 'Get status', but it doesn't explicitly state that no modifications occur, mention authentication requirements, or describe potential errors. It adds some value by listing return fields, but not fully comprehensive.

  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 concise and well-structured, with a one-line purpose statement followed by a bulleted list of key return fields. Every sentence adds value, and there is no filler or repetition.

  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 simplicity (no parameters, low complexity) and the presence of an output schema, the description is sufficiently complete. It identifies the main return fields and indicates there are additional metrics, which is acceptable for a status endpoint. It doesn't need to explain return values in depth because an output schema exists.

  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 tool has zero parameters, so the schema fully covers parameter semantics (the schema shows an empty object). The description adds no parameter-specific information, but per rubric, 0 params baseline is 4, and no further compensation is 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 clearly states the tool's purpose: 'Get the current status of the HedgeDoc instance.' It specifies the resource (instance) and the action (get status), and lists concrete return fields (note_count, online_users) that distinguish it from sibling tools like hedgedoc_read or hedgedoc_info, which focus on note content or specific note details.

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

  Usage Guidelines3/5

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

  The description implies usage for checking instance health/metrics but provides no explicit guidance on when to use this tool versus alternatives like hedgedoc_info. It doesn't mention exclusions or prerequisites, but the purpose is self-evident enough for simple status checks.

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

• hedgedoc_createA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses that the ID is random, the title becomes a level-1 heading, and the tool returns note ID and URL. It also mentions anonymous usage limitations. This is solid but does not cover failure modes or error conditions.

  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 concise and front-loaded, with a clear first sentence and a compact bullet list. Every sentence adds value, including the authentication note, with no fluff or repetition.

  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 create tool with two required parameters and an output schema, the description is quite complete. It covers return values and authentication prerequisites. It could be more thorough about instance configuration requirements or error behavior, but overall it is sufficient.

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

  Parameters4/5

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

  The schema has 0% coverage, so the description compensates by explaining title is added as a level-1 heading and content is the markdown body. This adds meaning beyond the raw schema fields, though it does not describe formatting constraints or length limits.

  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 the tool creates a new HedgeDoc note with a random ID, using a specific verb and resource. It also distinguishes from siblings like hedgedoc_create_with_alias by emphasizing random ID generation.

  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 note about HedgeDoc 1.x not using API tokens and working anonymously provides some usage context. However, it does not explicitly state when to prefer this tool over alternatives like hedgedoc_create_with_alias or hedgedoc_create_blank, so guidance remains implicit.

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

• hedgedoc_create_blankA
  4.2/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 default template behavior and that it returns the note ID and URL. However, it doesn't mention authentication, side effects, or errors. This is adequate but not rich.

  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?

  Three short sentences: purpose, usage context, and return value. No filler, front-loaded, every sentence earns its 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?

  Given the simplicity (0 params) and presence of an output schema, the description covers the essential creation behavior, usage context, and return info. It could add explicit alternatives, but that's partially addressed in usage guidelines. Lack of auth/permission details is a minor gap for a create 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 tool has 0 parameters and schema coverage is 100%, so there is nothing for parameter documentation to add. Baseline for 0 params is 4.

  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 has a specific verb ('Create'), resource ('HedgeDoc note'), and scope ('blank', 'default template content'), clearly distinguishing it from sibling tools like hedgedoc_create (which likely takes content) and hedgedoc_create_diagram.

  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 clear context: 'Useful for quickly starting a new note without providing content upfront.' This implies when to use it, but does not explicitly name alternatives or exclusions.

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

• hedgedoc_publish_urlA
  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 burden of behavioral disclosure. It explains that publish mode renders without the editor UI and is read-only, but does not mention side effects, error conditions, permissions, or whether this is a pure retrieval operation. This is adequate but not rich.

  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 and front-loaded with the core purpose. Each sentence earns its place: the what, the why, the parameter detail, and the return value. No redundancy or 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 a simple single-parameter URL-getter, the description covers the main purpose, the use case, the parameter meaning, and the return value. The presence of an output schema means return details are handled elsewhere. Missing edge cases like nonexistent note IDs are not covered, but this is acceptable for a low-complexity 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?

  Schema description coverage is 0%, and the schema only provides the parameter name and type. The description compensates by explaining that note_id is 'The note ID or alias (the slug from the URL),' adding meaningful context beyond the structured field.

  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: 'Get the published (read-only) URL of a HedgeDoc note.' It clearly distinguishes from siblings like hedgedoc_slide_url and hedgedoc_read by focusing on the publish/read-only URL concept.

  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 states the intended use case: 'ideal for sharing with viewers who should not edit the content.' This gives clear context but does not explicitly name alternative tools or exclusions, so it stops short of full when-to-use/not-use guidance.

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

• hedgedoc_slide_urlA
  4.2/5.0
  Behavior3/5

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

  Since no annotations are provided, the description carries the full burden. It states the tool returns a URL and explains what slide notes are, but does not disclose potential behaviors such as errors for non-slide notes, whether the note must exist, or any validation. This is adequate for a simple getter but not richly transparent.

  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 concise and front-loaded, with the main purpose in the first sentence. It includes a brief explanatory note on slides and a clear parameter bullet, with no redundant or filler content.

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

  Completeness4/5

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

  The tool is simple, with one required parameter and an output schema (not shown). The description explains the tool's purpose, the parameter, and the return value ('Returns the slide URL'), which is sufficient for a straightforward read operation. It lacks explicit error-handling details, but the output schema likely covers return structure.

  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 schema description coverage at 0%, the description compensates by explicitly explaining the single parameter: 'note_id: The note ID or alias (the slug from the URL)'. This adds meaningful meaning beyond the bare schema definition, though it could be slightly more detailed about accepted formats.

  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: 'Get the slide presentation URL of a HedgeDoc note.' It uses a specific verb and resource, and explains the slide-rendering context, distinguishing it from sibling tools like hedgedoc_publish_url.

  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 the tool (for notes designed as slides, useful for meetings), but does not explicitly mention alternatives or exclusion criteria. It implies usage rather than naming alternatives, so it lacks the explicit when-not-to-use guidance of a 5.

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

• hedgedoc_create_diagramA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It explains the return value ('Returns the note ID and URL'), clarifies the structure of diagram_code (without type header), and notes that HedgeDoc 1.x renders Mermaid natively. While it does not describe side effects like access permissions or error behavior, it provides substantial insight into how the tool operates, surpassing typical minimal descriptions.

  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, front-loaded with the main action, and uses a bulleted list for parameters. A note about HedgeDoc 1.x follows directly. While the parameter list duplicates schema information, it adds essential context given the schema's lack of descriptions. The overall length is appropriate, though the bullet list could be slightly condensed if descriptions existed.

  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 essential aspects: what the tool does, the parameter semantics, and the return value. The existence of an output schema reduces the need to detail return values, but the description still mentions them. It does not address potential limitations like invalid Mermaid syntax or authentication requirements, but for a create-note tool, the provided context is solid. The inclusion of diagram type examples and the note about native rendering adds valuable 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 has 0% description coverage, so the description must compensate. It does so excellently by explaining each parameter: title, diagram_type with examples, diagram_code with the important caveat 'without the type header,' and description as optional explanatory text. This adds meaning well beyond the bare schema field names and titles.

  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 action: 'Create a HedgeDoc note with a Mermaid diagram.' It specifies the resource (HedgeDoc note) and the special purpose (diagram), effectively distinguishing it from siblings like hedgedoc_create_blank and hedgedoc_create. The mention of native Mermaid rendering in HedgeDoc 1.x reinforces the tool's unique focus.

  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—whenever a Mermaid diagram note is needed. However, it does not explicitly exclude other note-creation tools or name alternatives. The examples of diagram types and the note about rendering imply its specific use case, but the absence of explicit 'when not to use' guidance prevents a perfect score.

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

• hedgedoc_list_revisionsA
  4.5/5.0
  Behavior4/5

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

  With no annotations present, the description carries the disclosure burden. It reveals that each revision entry contains an id (Unix timestamp) and length (chars), the return type is a JSON array, and the id can be used with another tool. It does not disclose error behavior or authentication, but for a read-only listing tool this is adequate.

  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 and front-loaded with the primary action, then provides necessary detail about output format and usage. Every sentence contributes value, 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?

  For a simple one-parameter tool, the description fully covers the purpose, the parameter meaning, return structure, and integration with a sibling tool. The presence of an output schema further covers detailed return types, so the description is appropriately 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?

  The only parameter note_id is not described in the schema (0% coverage), but the tool description provides a concise explanation: 'The note ID or alias (the slug from the URL).' This adds semantic meaning beyond the schema and clarifies what the agent should pass.

  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 lists all available revisions of a HedgeDoc note, using the specific verb 'List' and resource 'revisions.' It also distinguishes itself from the sibling hedgedoc_get_revision by implying the listing role and referencing the retrieval tool.

  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 a clear usage context: list revisions first, then use the revision-id with hedgedoc_get_revision to retrieve content. This effectively tells an agent when to use this tool vs the alternative, though it doesn't explicitly state 'use this to list, not to read.'

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

• hedgedoc_create_with_aliasA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavior disclosure. It discloses the requirement for FreeURL mode, explains that the title will be 'added as level-1 heading', and states that the tool 'Returns the note ID and URL'. It does not cover conflict behavior or other edge cases, but the key side effects and return values are well documented.

  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 concise and well-structured. It opens with the one-sentence purpose, follows with the prerequisite, then lists parameters in a bulleted format, and closes with the return value. Every sentence adds value with no 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?

  For a tool with 3 required scalar parameters, the description fully covers the purpose, prerequisite, parameter meanings, and return values. Output schema is present but the description still mentions what is returned (ID and URL). It is complete enough for an agent to select and invoke the tool correctly.

  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?

  Schema description coverage is 0%, so the description fully compensates by providing explicit semantics for each parameter: alias is a 'custom URL slug', title will be 'added as level-1 heading', and content is 'markdown body content'. This adds meaning beyond the bare schema types and titles.

  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: 'Create a new HedgeDoc note with a custom URL alias.' It uses a specific verb and resource, and the emphasis on 'custom URL alias' differentiates it from sibling tools like hedgedoc_create and hedgedoc_create_blank.

  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 by specifying the prerequisite that 'HedgeDoc's FreeURL mode' must be enabled, along with the exact environment variable. It implies the use case (custom alias creation) but does not explicitly state when to choose this tool over alternatives. This aligns with 'clear context, no exclusions'.

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