Server Quality Checklist

Tool Scores

• beat_insert_textB
  3.3/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 explaining side effects, but it only states that text is inserted at a character index and cites the index source. It does not disclose what happens to existing text, whether an open document is required, whether the operation returns a result, or whether the change is destructive. This is thin behavioral coverage 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 a single front-loaded sentence that states the core operation and immediately adds the key source constraint in parentheses. Every phrase earns its place, and there is no redundant restatement of the title.

  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 definition is minimally viable for a straightforward insertion call: it identifies the operation, the target resource, and the source of valid index values. However, it lacks guidance for choosing between insertion and append/set, does not define character-offset semantics, and provides no error or return context. With no annotations and no output schema, an agent still has to infer several important details.

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

  Parameters3/5

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

  The schema already documents index and docIndex, and the description adds the useful fact that indexes come from the outline/scene tools. However, the required text parameter has no description in the schema and no description in the prose, leaving its semantics to be inferred from the tool name. The description only partially compensates for the schema coverage 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 that the tool inserts text at a specific character index in a Beat document, and it tells the agent where valid indexes come from (beat_get_outline/beat_get_scenes). This makes the core operation unambiguous, but it never explicitly contrasts this tool with siblings like beat_append_text or beat_set_text, so it stops short of full 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 Guidelines3/5

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

  The description gives a useful precondition — indexes come from beat_get_outline/beat_get_scenes — and the schema clarifies docIndex. However, it does not state when to choose this over beat_append_text or beat_set_text, nor does it provide 'use X instead' guidance. Usage is implied rather than explicit, so it does not fully satisfy the when-vs-alternatives requirement.

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

• beat_get_textA
  3.6/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 disclosure burden. It signals a read operation via 'Get' and specifies the returned content (complete Fountain text), but it does not add details about error behavior, the effect of omitting docIndex, or any other side effects. This is adequate for a simple getter 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 a single, tightly worded sentence with no filler. The core action and object are front-loaded, and every word 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?

  For a one-parameter read-only tool, this description is nearly sufficient. It identifies the exact output ('complete Fountain text'), distinguishes the scope from partial-text siblings, and the schema covers the parameter. It could be more complete by explicitly noting the fallback to the front document, but that is already in the schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the single optional parameter docIndex is already described in the schema. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

  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 retrieves the complete Fountain text of a Beat document, using a specific verb and resource. It is distinguishable from sibling tools like beat_get_scene_text or beat_get_outline because it says 'complete Fountain text,' though it does not explicitly name those alternatives.

  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 implied rather than explicit. The description makes clear this is for getting the full document text, which implies it should be used instead of scene-level or outline tools, but it offers no explicit when-to-use or when-not-to-use guidance.

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

• beat_append_textA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the full behavioral disclosure burden. It clearly states the core mutation—appending text to the end of the document—but does not mention side effects, separator/newline behavior, persistence or reversibility, or return value. The main action is transparent, but surrounding behavior is not.

  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?

  Single sentence with no filler. It front-loads the action, specifies the target resource, and immediately provides a realistic use case. Every word earns its place.

  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 append operation with one required string, the description plus the docIndex schema covers the minimum for invocation. However, without annotations or an output schema, it would be more complete if it addressed line-break behavior, whether it returns a result, and how it relates to beat_insert_text or beat_replace_scene.

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

  Parameters3/5

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

  The schema fully documents docIndex, while 'text' is only typed as string with no description. The tool description adds some semantic meaning to text via the example 'a new scene', but it does not clarify formatting, newline expectations, or content constraints. This partially compensates for the 50% schema coverage.

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

  Purpose5/5

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

  The description names a specific verb ('Append'), explicit resource ('Beat document'), and position ('to the end'), with a concrete example ('a new scene'). This clearly distinguishes it from siblings like beat_insert_text or beat_replace_scene.

  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 phrase 'to the end' and example 'a new scene' give clear context for selecting this tool over insertion or replacement tools. It does not explicitly name alternatives such as beat_insert_text or state when not to use it, so it stops short of full routing guidance.

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

• beat_pingA
  3.9/5.0
  Behavior3/5

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

  There are no annotations, so the description must carry behavioral disclosure. 'Check' and 'list' imply read-only behavior and the description covers its two observable actions, but it does not state what happens when Beat is unreachable, whether any state changes occur, or what the response contains. That leaves moderate ambiguity for a health-check 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?

  Two short sentences, front-loaded with the tool's action and ending with a crisp directive. Every word earns its place; no redundant phrasing.

  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 zero-parameter health-check tool with no output schema, this description is nearly complete: it states what is checked, what is listed, and when to call it. It could add expected output/error behavior, but 'Call this first' supplies the essential workflow context and there are no parameters or return annotations to reconcile.

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

  Parameters4/5

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

  The input schema has zero parameters, so there is nothing for the description to explain. The no-parameter baseline applies, and the description correctly implies an invocation with no arguments.

  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 names a clear verb+resource: it checks Beat's running/reachable state and lists open documents. It is clear on its own but overlaps with sibling beat_list_documents, and does not draw the distinction between merely listing documents and also validating connectivity.

  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 explicit 'Call this first' gives a definite sequencing rule, establishing this as the entry-point health check before other Beat tools. It does not provide when-not-to-use guidance or name alternatives (e.g., beat_list_documents for a pure document list), so it stops short of a 5.

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

• beat_get_scene_textA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears the full burden. It conveys that this is a read-only retrieval operation returning the full scene text, but it does not mention error behavior, whether invalid indexes produce failures, or any document-switching side effects. For a simple read operation this is acceptable 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?

  A single sentence with no wasted words, and the key source of sceneIndex is included. The description is appropriately front-loaded 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?

  For a small read-only tool with two documented parameters, the description plus schema gives an agent enough to call it correctly: which index to pass and how to optionally target a document. Lack of an output schema is mitigated by the phrase 'full text', and no complex behavior needs explanation.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both parameters already documented. The description adds minimal value beyond the schema, mainly reinforcing that sceneIndex comes from beat_get_scenes; docIndex semantics are only in 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?

  States a specific verb ('Get'), resource ('full text of a single scene'), and identifying parameter ('sceneIndex'), with provenance from beat_get_scenes. This clearly distinguishes it from beat_get_text and other scene-writing siblings.

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

  Usage Guidelines4/5

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

  The description makes clear that sceneIndex must come from beat_get_scenes, and the schema adds that docIndex can be omitted to target the frontmost document. It does not explicitly contrast when to prefer this over beat_get_text, but the scoping to a single scene makes the intended use fairly clear.

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

• beat_get_outlineA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries full responsibility. It discloses that the operation is a read-only 'get', what data is returned, and the ordering of the outline. It does not cover error cases or behavior when no document is open, but the core behavioral profile is clearly conveyed.

  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?

  A single, information-dense sentence that front-loads the verb and object, then packs in the result contents, ordering, and downstream usage. Every phrase earns its place with no filler.

  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 read-only tool with one optional parameter and no output schema, the description is complete: it says what is returned, in what order, and how the result feeds sibling tools. The optional document targeting is covered by the schema, so nothing essential is missing.

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

  Parameters3/5

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

  The input schema already describes docIndex fully, including its source list and default behavior when omitted. The description adds no parameter-specific detail, so it settles at the baseline score for high schema coverage.

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

  Purpose5/5

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

  States a specific verb ('Get') and resource ('full outline of a Beat document'), then enumerates exactly what is included: scene headings, sections, synopsis lines, and order. It also distinguishes itself from scene-only tools by explicitly mentioning the sceneIndex and its downstream consumers.

  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?

  Clearly implies when to use this tool: to retrieve the complete outline and obtain the sceneIndex needed by beat_get_scene_text/beat_replace_scene. It does not explicitly state when not to use it or contrast it with siblings like beat_get_scenes, so it stops short of a full 5.

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

• beat_get_scenesA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of disclosing behavior, and it does so by specifying the exact return fields: sceneIndex, heading text, and position, while explicitly excluding sections/synopses. It does not mention side effects, but the 'get' verb and read-only nature are clear enough for this simple retrieval tool.

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

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the core action and immediately clarifies the scope and return fields. Every word contributes value, and there is no redundant or filler content.

  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?

  This is a low-complexity tool with one optional parameter and no output schema, and the description fully specifies what is returned and what is excluded. An agent has enough information to select and invoke this tool correctly without additional context.

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

  Parameters3/5

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

  The input schema has 100% coverage for its single optional parameter, including a clear explanation of docIndex and its omission behavior. The description adds no additional parameter context, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('get') and resource ('scenes of a Beat document'), and immediately distinguishes itself from related tools by clarifying it returns no sections/synopses. This lets an agent differentiate it from beat_get_outline and beat_get_scene_text.

  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 clearly conveys that this tool is for retrieving only the scene list, not sections or synopses, which gives context for when to use it. It does not explicitly name alternative tools or state when-not-to-use conditions, but the focus on 'just scenes' provides sufficient guidance.

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

• beat_replace_sceneA
  4.3/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 clearly communicates the side effects: in-place replacement, the exact replaced region, and no changes to the rest of the script. It does not discuss reversibility or error behavior, but the core destructive semantics are explicit.

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

  Conciseness5/5

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

  The description is two tight sentences that state the action, the exact span, the identifier source, and the non-effect on the rest of the script. There is no filler and no redundant restatement of the title.

  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 small, well-schematized mutation tool, the description is complete: it tells the agent what gets replaced, how the target scene is identified, and what is left untouched. The optional docIndex and required text format are already covered by the schema, and no output schema exists to document.

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

  Parameters3/5

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

  The input schema already fully documents all three parameters with 100% coverage, including that text must include the scene heading and that docIndex defaults to the frontmost document. The description repeats only the sceneIndex source from beat_get_scenes and adds no new parameter-level syntax, so the baseline score applies.

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

  Purpose5/5

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

  States a specific verb and resource ('Replace a single scene's text in place'), defines the exact span ('heading through the line before the next scene'), and clarifies that the rest of the script is untouched. This clearly distinguishes it from beat_set_text, beat_insert_text, and beat_append_text.

  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 establishes the intended use: modify one existing scene by sceneIndex from beat_get_scenes, not insert, append, or replace the entire script. It lacks an explicit named alternative or 'when not to use' clause, but the single-scene scope and 'rest untouched' give clear routing context.

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

• beat_list_documentsA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral burden. It states the scope ('currently open'), the action ('List'), and the key output field ('docIndex'), which is sufficient to convey that this is a non-destructive listing operation with no side effects.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. Every element earns its place: the action, the scope, and the practical purpose of the returned docIndex.

  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 zero-parameter listing tool with no output schema, the description is complete. It tells the agent what is listed, what the output includes, and how to use that output with other tools, leaving no meaningful gap.

  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 and the schema is empty, so there are no parameter semantics to document. Per the rubric, this justifies a baseline of 4; the description appropriately does not invent unnecessary parameter details.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and resource ('every screenplay currently open in Beat'), and clearly states what the tool returns: the docIndex for each document. This makes its purpose unambiguous and distinguishes it from doc-specific sibling tools that require a docIndex.

  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 clearly signals that this tool should be used first to obtain a docIndex for other Beat tools. It gives clear context about the tool's role as a prerequisite, though it does not explicitly mention when not to use it or name alternative tools.

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

• beat_set_textA
  4.5/5.0
  Behavior4/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 clearly communicates that the tool replaces the entire document text, which implies a destructive, full-overwrite behavior. It does not describe side effects beyond the overwrite or response behavior, but the core destructive trait is explicit.

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

  Conciseness5/5

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

  The description is two sentences long with no wasted words. The core behavior is front-loaded, and the usage guidance for when to prefer an alternative is concise and immediately actionable.

  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 only two parameters, no output schema, and no annotations, this description is sufficient. It explains what the tool does, when to use it, and how it differs from the most relevant sibling, while the schema covers parameter details.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents both parameters adequately. The description reinforces that the input is 'new Fountain text' but does not add substantial meaning beyond the existing parameter descriptions.

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

  Purpose5/5

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

  The description states a specific verb, 'Replace', and a clear resource, 'the ENTIRE text of a Beat document', making the operation unambiguous. The title 'Rewrite the whole screenplay' reinforces the scope, and the description explicitly distinguishes it from beat_replace_scene, so an agent can tell them apart.

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

  Usage Guidelines5/5

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

  The description gives explicit usage guidance: 'Use this for full rewrites' and 'prefer beat_replace_scene for targeted edits so you don't disturb the rest of the script.' This clearly states when to use this tool versus the alternative, with no inference required.

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

• beat_inspect_documentsA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the debug-only nature and the version-dependent variability of the output. It does not explicitly say 'read-only' or 'no side effects,' but the inspect/dump framing makes that reasonably clear.

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

  Conciseness5/5

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

  Two short sentences with no filler. The debug-helper framing is front-loaded, and the usage guidance is embedded efficiently in the second sentence.

  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 no-parameter debug utility, the description covers purpose, trigger condition, output variability, and relationship to a sibling tool. Nothing essential is missing.

  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 there is no parameter documentation burden for the description to carry. The empty schema plus the description fully disambiguates the call signature.

  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 is specific: it is a debug helper that dumps raw document-object fields exposed by the installed Beat version. It clearly differentiates itself from beat_list_documents by describing its role as a diagnostic fallback.

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

  Usage Guidelines5/5

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

  Explicitly states when it should be used: only if beat_list_documents titles/paths look wrong. This gives the agent a concrete routing condition and names the sibling tool it complements.

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