Server Quality Checklist

Tool Scores

• await_user_responseA
  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. It only says 'wait for the user to respond' and omits critical behavioral details such as blocking semantics, timeout behavior, and what occurs on timeout. The existence of a timeout_seconds parameter is not reflected in the description, leaving the agent uninformed.

  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 concise sentences, front-loaded with the core action, and contains no irrelevant information.

  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 tool with only two parameters and no output schema, the description covers the basic 'what' and 'when', but omits important behavior like timeout handling and return value. This makes it minimally adequate but not fully complete.

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

  Parameters3/5

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

  Schema coverage is 100%, so both parameters are already described in the schema. The description adds no extra semantics beyond the schema's parameter descriptions, thus matching the baseline for full coverage.

  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 waits for a user message and is used when specific input is needed, which distinguishes it from messaging/notification tools. However, it does not explicitly differentiate from the sibling 'wait_for_new_prompt', so it stops short of full clarity.

  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 use case ('when you need specific input or instructions from the user'), offering practical guidance. However, it lacks explicit exclusions or alternatives, so it doesn't fully meet the 'when-not-to-use' criterion.

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

• get_pending_promptsA
  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 disclosing side effects. It fails to mention that reading prompts by default clears them (clear_after_read=true), which is a significant behavioral trait. The description only states it returns queued prompts, omitting the clearing action.

  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, front-loaded with the purpose and followed by usage timing. Every sentence earns its place with no 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 with one optional parameter and no output schema. The description covers the basic function and when to use it, but omits the clearing behavior and detail about return format, making it somewhat incomplete.

  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 fully describes the only parameter (clear_after_read) with a clear description and default. The description adds no additional parameter semantics, so baseline 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 identifies the tool's action: checking for pending prompts from the Telegram user. It uses a specific verb ('check') and resource ('pending prompts'), and the phrase 'Returns any queued prompts' clarifies the expected output. However, it doesn't explicitly differentiate from sibling tools like wait_for_new_prompt, though the usage context helps.

  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 explicit timing: 'Call this when the user asks you to check telegram or at the start of a session.' It gives clear context for when to use the tool, but doesn't mention when not to use it or mention alternatives.

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

• search_project_codeA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does state the return format (matching files, line numbers, snippets) and the use of grep, but it omits explicit statements about being read-only or potential limitations like case sensitivity or binary file handling.

  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, well-structured sentence that immediately states the action and the return format. It is concise and free of irrelevant details.

  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 straightforward search tool with no output schema, the description explains the purpose and return format adequately. It could be more complete by also explaining how file_types and max_results affect the search, but the essentials are covered.

  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 covers all three parameters (query, file_types, max_results) with descriptions. The tool description adds no extra semantic detail beyond what the schema already provides, so it meets the baseline but does not exceed it.

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

  Purpose5/5

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

  The description clearly identifies a specific verb ('Search'), resource ('code patterns in the project'), and mechanism ('using grep'). It also distinguishes the tool from siblings like read_project_file or list_project_files by emphasizing content search with line numbers and snippets.

  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 explicit guidance on when to use this tool instead of alternatives such as list_project_files or read_project_file. It does not state conditions or mention any sibling tools for comparison.

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

• request_change_approvalA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description must fully disclose behavior. It states that it requests approval but does not explain side effects (e.g., whether it blocks, notifies human approvers, or returns a status). This leaves important behavioral aspects unaddressed.

  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 concise sentences with no fluff. It front-loads the core purpose and adds a usage note, making it easy to scan.

  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 with only two parameters, and the schema covers parameter meanings. However, there is no output schema and no annotations, so the description should explain what the agent can expect after the request (e.g., a response via await_user_response). The lack of this information leaves the description adequate but incomplete.

  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%, meaning both parameters (change_summary and diff_preview) have descriptions in the schema. The description adds minimal value beyond that, only hinting at 'important modifications' and 'before they are committed.' This meets the baseline for high schema coverage but does not enhance parameter understanding.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: requesting approval for specific code changes. It uses a specific verb ('request approval') and resource ('code changes'), and it distinguishes from sibling tools like request_plan_approval by focusing on code changes rather than plans.

  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 'Use for reviewing important modifications before they are committed' provides clear context for when to use the tool. It does not explicitly exclude alternatives or mention when not to use it, but the usage context is well-defined.

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

• send_code_updateA
  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 of behavioral disclosure. It only states the action and intended use case. It does not mention whether the notification is asynchronous, whether failures are handled, or any side effects beyond sending. Since this is a send operation, a simple notification may not require extensive disclosure, but the lack of any behavioral context beyond the action itself is a notable 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 a single, tightly worded sentence that conveys purpose and usage guidance without wasting words. It is front-loaded with the action and target, making it immediately scannable. Excellent conciseness.

  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 with 4 well-documented parameters and no output schema. The description covers the purpose and timing, which is sufficient for basic invocation. However, without annotations or any note on return behavior or failure modes, an agent might not know what to expect after calling. It is adequate but not fully complete.

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

  Parameters3/5

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

  The input schema provides full descriptions for all 4 parameters (summary, file_path, change_type, diff_preview), achieving 100% coverage. The description adds no additional parameter semantics, so the baseline of 3 is appropriate—the schema already does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states the action ('Send'), the resource ('code update notification'), and the target ('Telegram'). It distinguishes from sibling tools like send_telegram_message by specifying 'code update', making the purpose specific and actionable.

  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 explicit timing guidance ('Use after making significant code changes to inform the user'), which clarifies when to use the tool. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select this over general messaging tools.

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

• wait_for_new_promptA
  3.7/5.0
  Behavior3/5

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

  The description discloses key behavioral traits: it blocks until a prompt is found or timeout, and it is efficient for loop usage. However, with no annotations provided, the description must carry the full burden of behavioral disclosure. It does not explain what the tool returns (e.g., the prompt or null on timeout) or whether it consumes the prompt, leaving important behavioral aspects undocumented.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the main action, and every sentence adds value. It clearly states what the tool does, when to use it, and key constraints, without any 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?

  Given the tool is simple with one optional parameter and no output schema, the description covers the core purpose and usage. However, it lacks critical contextual information about the return value (what the caller gets upon success or timeout) and potential side effects. This is a notable gap for an agent deciding how to handle the result.

  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 covers 100% of parameters, including a clear description for timeout_seconds. The tool description merely mentions 'timeout' indirectly when saying 'or timeout is reached,' adding no new semantic value beyond the schema. With full schema coverage, a baseline of 3 is appropriate.

  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 function: waiting for a new prompt from Telegram and blocking until a prompt arrives or timeout. It specifies the resource (Telegram) and the action (wait for new prompt). However, it does not explicitly differentiate from sibling tools like await_user_response, which could also involve waiting for user input, so it misses a clear distinguishing factor.

  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 explicit usage guidance: 'Use this in a loop to monitor for incoming tasks.' This tells the agent when to invoke the tool. It does not mention when not to use it or suggest alternatives, but the loop context is a clear and useful directive.

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

• write_project_fileA
  3.7/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 mentions creating parent directories, but this is also in the schema. It does not disclose whether the tool overwrites existing files, whether it requires special permissions, or any side effects beyond the write itself. This is a significant gap for a potentially 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.

  Conciseness5/5

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

  The description is concise and front-loaded, with the core action stated first ('Write content to a file in the project'). Each sentence adds essential information: the action, a key behavior (creating parent directories), and a usage hint. 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?

  Given the tool has three parameters fully described in the schema, the description provides enough to understand the main purpose and basic usage. However, as a mutating tool without annotations, it lacks critical information about overwriting behavior and error handling. The lack of an output schema means return values are unexplained, but this is less critical for a write operation.

  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 provides full descriptions for all three parameters (file_path, content, create_dirs), so the baseline is 3. The description does not add any new parameter-level details; it merely echoes the create_dirs behavior that is already documented 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?

  The description clearly states the tool writes content to a project file, which is a specific verb+resource pair. The phrase 'Use for code modifications' helps differentiate it from siblings like read_project_file and list_project_files, which serve different purposes.

  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 a clear usage context ('Use for code modifications'), indicating when this tool is appropriate. However, it does not explicitly mention alternatives or situations where the tool should not be used, missing an explicit when-not-to-use clause.

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

• request_plan_approvalA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does disclose that the user sees the plan and can approve/reject, which is helpful. However, it omits details such as whether the tool blocks further execution, what happens on rejection, or what the tool returns once approval is requested.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the primary purpose, then a specific usage trigger and user-experience note. No wasted words; each sentence contributes essential information.

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

  Completeness4/5

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

  For a simple tool with three fully-described parameters and no output schema, the description covers purpose, timing, and user interaction adequately. It could optionally mention the return value or approval result, but the description is sufficient 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.

  Parameters3/5

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

  The input schema has 100% description coverage for all three parameters, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides.

  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 ('request approval') and the resource ('implementation plan'), with a specific scope ('before modifying more than 3 files or making significant changes'). It does not explicitly distinguish between this and the sibling tool 'request_change_approval', but the implementation-plan focus provides reasonable separation.

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

  Usage Guidelines4/5

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

  Provides explicit trigger conditions ('Use this before modifying more than 3 files or making significant changes') and describes the user-facing outcome (user sees summary, can approve or reject). Lacks exclusions or explicit alternative references, but the context is clear and actionable.

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

• run_terminal_commandA
  3.8/5.0
  Behavior2/5

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

  No annotations are provided, so the description bears full responsibility for disclosing behavioral traits. While it mentions the return values, it fails to warn that executing a terminal command can have arbitrary side effects (e.g., modifying files, running network operations, or being destructive). For a command execution tool, this is a significant safety 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 exceptionally concise, front-loading the main action and output, followed by a brief usage hint. Every sentence contributes value without redundancy.

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

  Completeness4/5

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

  For a tool with only two parameters and no output schema, the description covers the essential return values (stdout, stderr, return code) and a typical use case (builds/tests). However, it omits critical safety context and environment details, such as working directory behavior or potential side effects, which prevents a perfect score.

  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 provides full descriptions for both parameters ('command' and 'timeout') with 100% coverage. The description adds no extra parameter-level meaning, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states a specific action ('Run a terminal command'), the context ('in the project directory'), and the expected output ('Returns stdout, stderr, and return code'). This distinguishes it from sibling tools like read_project_file or send_telegram_message, which serve different purposes.

  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 use case ('Use for builds, tests, etc.'), which communicates when the tool is appropriate. However, it does not explicitly exclude alternatives or mention when not to use it, though the sibling tool names imply a distinct domain.

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

• send_telegram_messageA
  3.8/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 responsibility for disclosing side effects. It only states that the tool sends a message and doesn't require approval, but does not disclose delivery semantics, asynchronous behavior, failure modes, or any prerequisites. For an action tool with no 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.

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the primary purpose, and every word earns its place. It avoids redundancy and clearly conveys both purpose and usage context with no fluff.

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

  Completeness4/5

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

  For a simple messaging tool with only two parameters and no output schema, the description covers the essential aspects for an agent to select and invoke it: the action, the channel, and the appropriate use cases. It doesn't explain return values, but that's not critical for a send operation, and 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 baseline is 3. The description adds no additional meaning beyond the schema, which already documents both parameters ('message' and 'priority') with clear descriptions. The description doesn't compensate for any gaps, but none exist.

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

  Purpose5/5

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

  The description clearly states the verb and resource: 'Send a message to the user via Telegram.' It also specifies the acceptable use cases ('status updates, informational messages') and explicitly differentiates from sibling tools by noting it's for communication that doesn't require approval, which distinguishes it from approval-request tools.

  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 when-to-use context: 'status updates, informational messages, or any communication that doesn't require approval.' It implies exclusions (approval-required communication) but does not explicitly name alternative tools like request_plan_approval or notify_error, so it falls just short of full guidance.

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

• list_project_filesA
  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 carries the full burden. It implies read-only behavior through the verb 'list' but does not explicitly state that it makes no modifications. It also does not mention behavior around hidden files or sorting, but for a simple listing tool, the description is minimally 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 two sentences, front-loaded with the core action, and every word earns its place. It is concise and free of 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 list tool with all parameters documented in the schema, the description covers purpose and usage effectively. It does not describe the output format, but with no output schema and a straightforward list operation, this is acceptable. The tool is adequately specified for an agent to select and invoke it correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds context about pattern matching, but does not elaborate on directory or recursive semantics beyond what the schema already provides. No additional value is needed since the schema fully documents parameters.

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

  Purpose5/5

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

  The description clearly states the tool lists files and directories, with a specific verb and resource. It distinguishes itself from sibling tools like read_project_file (reading content) and search_project_code (searching code) by focusing on structure exploration and pattern matching.

  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 usage context: 'Use to explore project structure or find files matching a pattern.' This gives reasonable guidance on when to use the tool, though it does not explicitly mention alternatives or exclusions, which is acceptable given the tool's straightforward nature.

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

• read_project_fileA
  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 carries the full burden. The verb 'Read' implies a non-mutating operation, but the description doesn't explicitly state read-only behavior, error handling, or return format. It adds usage context but is sparse on behavioral traits.

  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, front-loaded with the core purpose and then a succinct usage note. Every word earns its place with no redundancy.

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

  Completeness4/5

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

  For a simple read tool with 3 parameters and no output schema, the description provides sufficient context: it states what the tool does and when to use it, while the schema covers parameter details. Missing explicit return-value description is minor for such an obvious operation.

  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 explains file_path, start_line, and end_line. The description does not add extra meaning to these parameters, warranting the baseline score of 3.

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

  Purpose5/5

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

  The description clearly states the tool reads file contents from the current project, using a specific verb and resource. It distinguishes from sibling tools like write_project_file, list_project_files, and search_project_code.

  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 explicit use cases: 'report file contents back to Telegram or verify changes.' It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to know when to use this read tool.

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

• send_artifactA
  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 must carry the transparency burden. It states the action and channel (send via Telegram) but does not disclose potential behaviors like file size limits, error handling, or whether the operation blocks until delivery. This is a moderate gap for a send operation.

  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 concise sentences, front-loaded with the core action and followed by a usage hint. Every word earns its place with no redundancy.

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

  Completeness4/5

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

  For a simple 2-parameter tool with no output schema, the description adequately covers the purpose, usage timing, and content type. It lacks detail on return behavior, but that is not critical for this type of tool.

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

  Parameters3/5

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

  Schema coverage is 100% with both artifact_path and caption described. The description adds no additional parameter meaning, but the baseline of 3 is appropriate since the schema fully documents the parameters.

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

  Purpose5/5

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

  The description clearly states the tool sends an artifact (screenshot, recording, or file) via Telegram, using a specific verb and resource. It distinguishes itself from sibling tools like send_telegram_message by explicitly focusing on non-text content.

  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 timing guidance ('Use after capturing UI screenshots or generating visual content'), implying when this tool is appropriate. It does not explicitly mention alternatives or when not to use it, but the context is sufficiently clear given the sibling tools.

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

• set_project_contextA
  4/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. It discloses an important behavioral trait—file operations become relative to this path—but lacks details about persistence, validation, or what happens if the path is invalid. This is adequate but not 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?

  Two sentences, front-loaded with the core action, and zero wasted words. It efficiently communicates both purpose and effect.

  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 setter tool with one parameter and no output schema, the description is fairly complete. It explains what the tool does and its effect on other operations. Missing details like persistence or how to query the current context are minor given the tool's simplicity and the presence of get_project_context among siblings.

  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 the parameter as 'Absolute path to the project directory.' The description adds the behavioral context that file operations will be relative, but does not add further parameter-specific syntax or format details 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 clearly states the tool's function: 'Set the current project path for IDE operations.' It uses a specific verb ('set') and resource ('project path'), and distinguishes from sibling tools like get_project_context by indicating it sets rather than retrieves context.

  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 the tool by stating 'All file operations will be relative to this path,' which signals it should be called before file operations. It does not explicitly name alternatives like get_project_context, but the context is clear enough for an agent to infer usage.

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

• update_statusA
  4/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 reveals that the tool edits the existing status message, which is a key behavior, but it does not explain edge cases like what happens if no status message exists, how progress_percent affects the message, or whether the update is idempotent. This is partial transparency.

  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 at two sentences, front-loaded with the primary purpose and immediately followed by a key behavioral distinction. Every word earns its place with no redundancy.

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

  Completeness4/5

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

  For a tool with only two simple parameters and no output schema, the description provides adequate context. It explains the core function and unique differentiator. Minor missing details, such as behavior when no status exists, prevent a perfect score, but overall it is sufficiently complete for a low-complexity tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both parameters explained clearly in the input schema. The description does not add extra parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Update the status ticker message.' It also distinguishes it from siblings by explaining it edits an existing message rather than sending a new one, which aligns with the sibling tools like send_telegram_message.

  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 usage context: use this to update an existing status message instead of sending a new one, thereby reducing message spam. It implies the alternative (sending a new message) without naming specific sibling tools, but the guidance is sufficient for selecting this tool.

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

• get_project_contextA
  4.1/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 transparently discloses the operation ('Get information') and the exact return contents (project path, file counts by type, git status, settings), making the behavior clear. It does not mention potential side effects, but for a read-only getter this is largely sufficient.

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

  Conciseness5/5

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

  The description is two short sentences, front-loaded with the purpose, and every word earns its place. It lists specifics without fluff, making it highly efficient.

  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 tool with no output schema, the description is complete: it states the purpose and enumerates all return elements. No additional context appears necessary for correct use.

  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 description does not need to explain parameter semantics. Per rubric, a baseline of 4 applies. The description adds no param info, but none 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 uses a specific verb ('Get') and resource ('current project context'), and enumerates the returns (project path, file counts, git status, settings). This clearly distinguishes it from siblings like read_project_file (which reads a specific file) and set_project_context (which likely mutates context).

  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 implies it is for getting an overview of the project, but does not mention when to prefer this over read_project_file or list_project_files, nor any exclusions.

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

• notify_errorA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates the tool sends a user-facing critical error notification, which is the primary side effect. The description is straightforward and does not hide any surprising behavior, making it sufficiently 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 just two sentences with no filler. The first sentence states the action, and the second gives usage guidance. Every word earns its place, making it highly concise and well-structured.

  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 notification tool with three well-documented parameters and no output schema, the description adequately covers purpose and usage. It does not mention whether the call returns a value or is asynchronous, but these are not critical for such a basic tool, and the description is complete enough for an agent to invoke it correctly.

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

  Parameters3/5

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

  The input schema provides descriptions for all three parameters (error_message, command, stack_trace) with 100% coverage, so the schema already gives the necessary parameter semantics. The description adds no direct parameter details, but that is acceptable since the baseline is 3 when schema coverage is high.

  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 that the tool sends a critical error notification to the user, with a specific verb ('Send') and resource ('critical error notification'). It distinguishes itself from sibling tools like send_telegram_message by emphasizing the error-specific nature and the need for user attention.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool: when terminal commands fail or errors occur that need user attention. This provides clear usable context, though it does not mention alternative tools or explicitly say when not to use it, stopping just short of the full 5.

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