HAOps MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v2.8.0
Disambiguation4/5
Most tools have distinct purposes with clear descriptions, but there is some overlap (e.g., multiple 'claim' tools, bulk vs individual skill updates). The descriptions help differentiate, but the sheer number may still cause confusion.
Naming Consistency5/5
All tools follow a consistent 'haops_verb_noun' pattern (e.g., haops_list_issues, haops_create_feature). Naming is uniform and predictable across the entire set.
Tool Count2/5
With 137 tools, the surface area is extremely large. While it reflects a comprehensive system, it likely includes many rarely used tools and can overwhelm agents. A more focused set would be preferable.
Completeness4/5
The tool set covers a wide range of domains (project management, git, helpdesk, documentation, skills, protocols, memory). There are minor gaps (e.g., missing some lifecycle transitions), but overall it is quite complete for the stated purpose.
Average 3.8/5 across 137 of 137 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 32 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks any disclosure of behavioral traits. With no annotations, it should explain what happens upon creation (e.g., returns the issue, validation, side effects), but it only states the operation itself.
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 a single, short sentence with no unnecessary words. However, it is so brief that it misses opportunities to add value. It is front-loaded but under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters and no output schema, the description is insufficient. It does not explain relationships between parameters (e.g., projectSlug, featureId) or what the tool returns, making it incomplete for an AI agent.
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 the schema already describes each parameter. The description adds no additional meaning beyond 'in a HAOps feature', which is loosely implied by the featureId parameter. 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 states the action 'create' and the resource 'issue' within 'a HAOps feature', which distinguishes it from sibling tools like update, delete, or list. However, it could be more explicit about what constitutes a HAOps feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as haops_bulk_update_issues or haops_update_issue. There is no mention of prerequisites or best practices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states that the tool creates a channel, with no details on side effects, required permissions, error handling (e.g., duplicate name), or the role of the 'verbose' parameter affecting response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but may be too brief for a 5-parameter tool. It front-loads the core purpose but lacks additional context that could be included without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description is incomplete. It does not explain what a channel is, when to create one, the meaning of different types, or the response format despite having a 'verbose' parameter.
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 tool description adds no extra meaning beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a new channel') within the context ('in a HAOps project'). It distinguishes from sibling tools like haops_create_issue by specifying 'channel', though it could add more context about what a channel is used for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like haops_update_channel or haops_delete_channel. No prerequisites (e.g., project must exist) or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only restates the basic action, omitting details like whether pinning is visible to all, permission requirements, or side effects such as notifications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks substance. It could be expanded with useful details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description is too minimal. It does not explain the effect of pinning, the need for valid discussion/message IDs, or any expected outcomes.
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 the schema already documents parameters. The description adds no extra meaning; it does not clarify parameter relationships or usage patterns. Score at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (pin or unpin) and the resource (discussion message). It is specific enough to distinguish from siblings like haops_edit_message or haops_delete_message, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. There is no mention of prerequisites, context (e.g., 'use this when you want to highlight a message'), or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It only states the action and return type, but omits side effects, permissions, performance implications, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded, no redundancy. Could be slightly more concise by merging 'generates changelog from audit logs' and 'returns structured content', but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, yet the description does not explain the structure of the returned changelog content. Missing details on time range, filtering, or format. Not complete for a generation 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%, so the schema already describes both parameters. The description does not add extra meaning beyond what's in the schema, e.g., how 'verbose' affects output.
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 'Generate' and resource 'changelog from audit logs for a project'. It distinguishes from siblings like haops_get_audit_log by focusing on transformation, but does not explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., haops_get_audit_log for raw logs). No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'Returns test records with metadata.' It does not disclose that this is a read-only operation, nor does it mention common behavioral traits like pagination, default limit, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose. It is concise, but could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are 7 parameters and no output schema, the description is minimal. It does not mention default values for limit, pagination behavior, or that the required projectSlug must be a valid project identifier. It is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds only 'with optional filters', which is already clear from the schema. It does not provide additional meaning or context for any parameter.
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 'List tests in a project' with optional filters and returning metadata. This distinguishes it from other tools that list issues, features, etc., but does not explicitly differentiate from haops_list_test_runs or haops_list_test_suites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as haops_list_test_suites or haops_list_test_runs. The description lacks any 'when to use' or 'when not to use' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It states 'list' implying read-only, but fails to disclose pagination, sorting, or any other 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core purpose. It is efficient but could benefit from additional context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one param, no output schema), the description should hint at the return value, but it does not. The tool feels 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 covers 100% of parameters with a description of projectSlug. The tool description adds no extra meaning beyond the schema, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List test suites for a project' clearly states the verb and resource, but does not differentiate from sibling tools like haops_list_tests or haops_export_test_suite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives such as haops_list_tests for individual test cases or haops_export_test_suite for exporting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the basic purpose without explaining whether the update is partial, what happens on failure, permission requirements, or side effects. This is insufficient 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the essential purpose. However, it could add more value without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 12 parameters, the description is too sparse. It does not explain return values, partial update behavior, or any conditional logic. The tool is moderately complex but lacks supporting 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?
Schema coverage is 100%, so the input schema fully documents each parameter. The description adds no additional meaning beyond the schema. Per guidelines, baseline 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 action ('Update') and the resource ('an existing feature in a HAOps module'). It distinguishes from creation (haops_create_feature) and deletion (haops_delete_feature) but does not explicitly differentiate from other update tools. The verb and resource are specific enough, earning a 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or conditions for updating a feature, nor any comparison to sibling tools like haops_update_issue or haops_update_module.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only says 'create', implying mutation, but does not detail side effects, authentication needs, or whether the operation is reversible.
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 a single, front-loaded sentence that efficiently states the tool's purpose. While it is very short, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 12 parameters, no output schema, and no annotations, the description is incomplete. It does not mention return values, success behavior, or error cases, which are critical for a create 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 baseline is 3. The description adds no parameter-level information beyond what the schema already provides.
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 ('Create'), the resource ('new feature'), and the context ('in a HAOps module'). This distinguishes it from siblings like haops_create_issue or haops_create_module, which have different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like haops_create_issue or haops_create_ticket. It lacks any context about prerequisites, exclusions, or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 disclosing behavioral traits. It only states the tool 'creates' a module, implying a write operation, but does not mention permissions, reversibility, side effects, or any impact on related entities. This is insufficient 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 extremely concise: one sentence with eight words. It is front-loaded with the essential action and resource, and every word is meaningful. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, no output schema) and full schema coverage, the description is minimally adequate. It states the core purpose but lacks context about project association, module semantics, or the relationship between required parameters. It does not explain what happens upon creation or how to interpret results.
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, so the description adds no additional parameter meaning beyond what the schema already provides. According to guidelines, baseline is 3 when coverage is high, and the description does not exceed this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and the resource ('a new module in a HAOps project'). It is specific and unambiguous. However, it does not differentiate from sibling create tools (e.g., haops_create_issue), missing the opportunity to help the agent choose this tool over others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, such as haops_update_module or haops_claim_module. There are no exclusions or context about prerequisites or common use cases, leaving the agent without direction beyond the basic verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions pagination but does not cover ordering, response format, side effects (read-only assumed but not stated), rate limits, or authentication. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the primary action front-loaded. No wasted words, but could be slightly more efficient without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters, the description lacks details on ordering, how to paginate (next page links?), returned fields, and error conditions. Incomplete for full understanding of tool behavior.
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 descriptions cover all 4 parameters (100% coverage). Description adds 'with pagination' hinting at page/limit but no additional meaning beyond what schema provides. 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?
Clearly states the tool retrieves messages from a discussion thread with pagination. The phrase 'Essential for reading conversation context before responding' adds purpose context. Slightly generic but distinguishes from siblings like get_discussion or post_message.
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?
Implies usage before responding to a discussion, but does not explicitly mention when not to use it or list alternatives. No guidance on prerequisites or relationship to other tools like get_discussion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations; description only states 'content and metadata' without detailing read-only nature, permissions, or error behavior.
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, direct, no filler. Efficiently communicates core functionality.
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?
Without output schema or annotations, description lacks detail on return format (content vs metadata). Adequate for a simple getter but not 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 covers 100% of parameters with descriptions. Description adds no extra parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'documentation section'. Distinct from sibling tools like list_doc_sections, create_doc_section, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral traits. It only mentions 'add or toggle' without clarifying whether toggling removes an existing reaction, idempotency, required permissions, rate limits, or response behavior (though the schema has a verbose param). The description is insufficient for safe invocation.
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 a single concise sentence, which is efficient. However, it omits important behavioral details, so while concise, it under-delivers for the necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain thoroughly. It fails to cover toggle semantics, error conditions, return value structure, or prerequisites (like needing discussion and message existence). The tool has 5 parameters but the description only hints at one.
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 baseline is 3. The description does not add any meaning beyond the schema descriptions. It mentions 'emoji' generally but does not elaborate on the other four parameters or their relationships.
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 action ('Add or toggle an emoji reaction') and the target resource ('discussion message'). It distinguishes itself from sibling tools like haops_post_message, haops_edit_message, and haops_pin_message by specifying a unique reaction-focused operation.
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 reacting to messages but does not explicitly state when to use this tool versus alternatives or provide context for when not to use it. No exclusions or comparisons to other reaction-related tools are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states status change, no info on permissions, side effects, or restrictions on reopening.
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?
Single concise sentence with no wasted words, but could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple operation but lacks usage context and behavioral details. No output schema, so description should compensate but does not.
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 baseline is 3. Description adds no extra meaning beyond the schema 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 clearly states the verb 'reopen', the resource 'merge request', and the effect 'sets status back to open'. It distinguishes from the sibling haops_close_merge_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Does not mention prerequisites or alternatives like haops_merge_merge_request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Merely says 'Update' without disclosing write behavior, partial update capability, idempotency, permissions, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that efficiently conveys the core purpose. No wasted words, but could benefit from additional brief context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is minimal; lacks details on return value behavior (despite verbose parameter), effect on issue, and any restrictions. Moderate complexity with 12 parameters and no output schema or annotations.
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 description adds no extra meaning. Baseline 3 is appropriate as schema already documents all 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 verb 'Update' and the resource 'existing issue', distinguishing it from create, get, and delete siblings. 'in a HAOps feature' adds context without confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., haops_create_issue, haops_delete_issue). No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral disclosure. It only states 'Update an existing module' without mentioning side effects, permissions, or whether fields are overwritten. For a mutation operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded. However, it omits important information that would improve its usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, 2 required, and no output schema, the description is too sparse. It does not explain the behavior, return value, or constraints, making it inadequate for an agent to fully understand the tool's 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?
Schema coverage is 100%, meaning all parameters have descriptions in the schema. The tool description adds no additional meaning beyond what the schema already provides, but the baseline is 3 due to full 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 'Update an existing module in a HAOps project' uses a specific verb and resource, clearly differentiating it from sibling update tools for other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as other update tools or create/delete operations. The description does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description merely says 'Delete' without detailing side effects, permission requirements, reversibility, or whether it's a soft or hard delete. For a destructive action, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no extraneous words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present. The description lacks important context for a deletion tool, such as return value format, error conditions, or impact on related entities. Given the destructive nature, more completeness is expected.
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 each parameter described (projectSlug, artifactSlug, sectionSlug, verbose). The description adds no additional parameter meaning beyond what the schema provides. Baseline 3 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?
The description clearly states 'Delete a section from a documentation artifact,' using a specific verb and resource. It distinguishes from sibling delete tools like haops_delete_doc_artifact and haops_delete_help_section by specifying 'doc section'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like haops_update_doc_section or haops_delete_doc_artifact. The description lacks context about prerequisites or scenarios where deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states the return data types but does not disclose behavioral traits like read-only nature, side effects, permissions required, or rate limits. The description is insufficient for an unannotated tool.
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 a single sentence that is concise and front-loaded with the main purpose. It efficiently communicates the core function and return types, though could be more structured (e.g., listing return fields). No wasted words.
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 has 3 parameters (1 required), no output schema, and no annotations. The description lists key return data (pass rates, trend, recent failures, coverage data) but does not specify format or structure. It is adequate for a simple read tool but leaves some ambiguity about the exact response shape.
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 the context 'for a project or specific entity', which implies filtering by entityId and entityType, but does not add significant meaning beyond the schema descriptions. Adequate but not enhancing.
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 'Get' and the resource 'aggregated test health summary', specifying what it returns (pass rates, trend, recent failures, coverage data). It distinguishes itself from sibling tools like haops_get_protocol_health and haops_work_entity_health_check by focusing on test health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no exclusion criteria, and no context about prerequisites or scenarios. With many sibling tools, the lack of usage guidance leaves the agent uncertain about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool sets testableType and testableId, implying modification, but does not disclose idempotency, whether it replaces existing links, or what error conditions exist.
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 concise sentences that front-load the action and method. Every word is necessary; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations or output schema, the description is too minimal. It lacks details on return value (beyond verbose parameter), error handling, and behavioral effects like whether linking is additive or destructive.
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 covers 100% of parameters with descriptions. The description adds 'by test IDs or file path pattern' which paraphrases the schema but does not provide significant new meaning. Baseline 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?
Description clearly states the action (link tests), the targets (module, feature, issue), and methods (by test IDs or file path pattern). It is distinct from sibling tools which focus on CRUD or other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or situations where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states it searches by keyword but does not disclose additional behaviors like result ordering, pagination, or search scope (e.g., only article content vs. titles). This is insufficient for a search 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 short sentences that are front-loaded with the action. Every word contributes meaning, making it highly concise with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too minimal. It lacks details on result format, limitations (e.g., pagination, matching algorithm), and does not differentiate from other search tools like haops_search_discussion. Completeness is low.
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 the 'query' parameter described as 'Search query string'. The description adds 'by keyword', which slightly reinforces usage but does not provide significant extra 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 clearly states the verb 'Search' and resource 'help articles', and specifies the output 'matching articles with titles and snippets'. This distinguishes it from siblings like haops_get_help_article (retrieval by id) and haops_list_help_articles (listing all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, such as haops_get_help_article for exact retrieval or haops_list_help_articles for browsing. The description lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits; it only says 'Update' without mentioning mutability, permissions, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no fluff, but could benefit from additional context while remaining concise.
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 no output schema and 5 parameters well-documented in schema, the description is adequate but lacks info on return value or usage 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?
Schema description coverage is 100%, so baseline 3; the description adds no additional meaning beyond schema, but schema itself is clear.
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 'Update' and the resource 'existing channel in a HAOps project', distinguishing it from create and delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like create or delete, no prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 only states that fields can be updated, but does not mention side effects, permissions, rate limits, or whether the operation is destructive. The status transition rules are in the schema but not reinforced in the description.
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 sentence that directly states the purpose with no unnecessary words. It is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, and the complexity of 7 parameters, the description is too minimal. It does not explain the response format, the effect of the verbose parameter, or error handling. It also does not differentiate from many sibling update tools.
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?
Input schema has 100% coverage with descriptions for all parameters. The description adds no additional meaning beyond listing some of the fields. It does not explain the purpose of required parameters like projectSlug or artifactSlug beyond what is 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 explicitly states the verb 'Update' and the resource 'documentation artifact', and lists the specific fields that can be updated (title, description, status, version). This clearly distinguishes it from sibling tools like create or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or when not to use it. The sibling list includes many update tools, but no differentiation is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry full behavioral disclosure. It only states the action without revealing important traits such as idempotency, permission requirements, or behavior if the user is already a member.
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 a single, efficient sentence that front-loads the core purpose. It could be slightly more structured but is generally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters and no output schema, the description is too minimal. It does not explain return values, failure modes, or behavioral details, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all four parameters, so the description adds no extra meaning. Baseline 3 is appropriate as the schema 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 defines the action ('Add') and the resource ('user as a member to a HAOps project'), distinguishing it from related sibling tools like haops_list_members (list) and haops_update_member_role (update).
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 adding a member to a project but does not provide explicit guidance on when to use this tool versus alternatives or prerequisites like ensuring the user is not already a member.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the article is created as unpublished by default, permission requirements, or what happens if the sectionSlug is invalid. The description is minimal and lacks transparency beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, making it concise. However, it is quite short and could benefit from a bit more context without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema or annotations, the description is insufficient. It does not explain return values, the effect of the 'verbose' parameter, or how to obtain the 'sectionSlug'. A more complete description is needed for agents to use 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?
Schema description coverage is 100% for all 5 parameters, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides, but does not need to since the schema is thorough.
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 'Create a new help article in a section' clearly states the action (create), the resource (help article), and the location (in a section). It distinguishes from sibling tools like haops_create_help_section and haops_update_help_article.
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 provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites like ensuring the section exists. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose side effects (e.g., notifications, permissions required, idempotency) beyond the fact that it's a manual creation on behalf of another user.
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 a single concise sentence (20 words) that is front-loaded and lacks unnecessary words. However, it could be slightly expanded to improve clarity without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain return values or the exact behavior (e.g., what is created, confirmation). For a creation tool, more context about response and effects is needed.
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 the schema already documents all parameters. The description adds minimal value beyond the schema (e.g., 'on behalf of a requester' is implicit from 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 creates a helpdesk ticket manually on behalf of a requester, specifying it's from an agent rather than a public form. This distinguishes it from other create tools like 'haops_create_issue' or 'haops_create_discussion'.
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 hints at agent-side usage but does not explicitly compare with alternatives like 'haops_create_issue' (for software issues) or 'haops_create_help_article'. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the admin-only restriction but does not explain the destructive nature, whether deletion is permanent, any cascading effects, or what happens after deletion. Minimal disclosure 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short at two sentences, making it efficient and front-loaded. However, it could include more detail without losing conciseness. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool is a destructive mutation with no output schema and only two parameters, the description fails to explain the consequences of deletion, error scenarios, or any required confirmation. It omits important behavioral 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?
Schema coverage is 100%, meaning the input schema already describes both parameters ('verbose' and 'articleSlug') adequately. The description adds no additional parameter-level information, so baseline 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 verb 'Delete' and the resource 'help article', which distinguishes it from update, get, and list siblings. It also adds an access control note ('Admin-only'), making the purpose precise.
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 that the tool is for admin users only, but does not provide guidance on when to use it versus alternatives like updating or listing. There is no explicit context about prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must inform about behavioral traits. It mentions creating new records with fresh UUIDs but omits details about side effects, permissions, idempotency, or error handling, leaving significant gaps.
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 a single concise sentence that front-loads the action. It is efficient but could include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has nested objects and no output schema, yet the description does not explain the return value or behavior after import. This lack of completeness is a gap for a tool of this complexity.
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 parameters thoroughly. The description adds no additional meaning beyond the schema, earning the baseline 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 imports a test suite from a JSON bundle into a project, specifying it creates new suite and test records. This distinguishes it from sibling tools like haops_export_test_suite and haops_list_test_suites.
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 importing a previously exported suite, but does not explicitly state when to use or alternatives. The schema description for 'bundle' references haops_export_test_suite, but the tool description itself lacks usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It lists returned fields but omits important behavior such as pagination (page and limit parameters), default sorting, total count, or error handling. This lack of information about how the tool behaves beyond the basic listing is a 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 extremely concise—two sentences that cover the core action, optional filters, and return value. Every sentence adds value with no fluff. It is front-loaded with the main purpose.
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 lack of output schema, the description adequately explains what the tool returns (feature ID, title, status, priority, owner, module, issue count). However, it misses contextual details like pagination behavior, ordering, and how the filters interact. With many sibling list tools, it is sufficient but not comprehensive.
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 all parameters. The description adds value by mentioning the moduleId filter explicitly and listing return fields, but it does not provide additional semantic context for parameters beyond what is in the schema. Baseline 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 action (list features) and the resource (HAOps project) with optional filters. It also specifies the return fields, making the purpose unambiguous. However, it does not explicitly differentiate from sibling list tools like haops_list_issues or haops_list_modules, though the focus on features is clear.
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 mentions optional filters and specifically calls out filtering by moduleId, which helps understand when to use this tool. However, it does not provide explicit when-to-use or when-not-to-use guidance relative to siblings (e.g., haops_get_feature for a single feature) or mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits like pagination, ordering, authentication needs, or that it's read-only. The minimal description leaves uncertainty about side effects and scope.
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 sentence with no wasted words. It is front-loaded with the verb 'List' and clearly identifies the resource.
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?
While the tool is simple with one optional parameter, the description lacks details about the return format, pagination, or result set. Without an output schema, the agent relies on the description, which is 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 coverage is 100% with a clear description of the parameter. The tool description simply rephrases the schema, adding no new meaning beyond what is already 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 action 'list help articles' and adds the optional filtering by section slug. It distinguishes from siblings like get_help_article and create_help_article by specifying it's a list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_help_sections or search_help. No when-not-to-use or context for using the filter optionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'List all members' but does not disclose if pagination applies, whether the list is filtered, or any side effects. Minimal behavioral context beyond the operation type.
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, concise sentence (13 words) that front-loads the key information. Every word is meaningful 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?
Given the simplicity of the tool (one parameter, no output schema) and many siblings, the description is adequate but lacks details on pagination, return format, or the meaning of 'activity stats'. It covers the basics but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'projectSlug' is described in the schema as 'The project slug (URL identifier)'. The description does not add semantic information beyond the schema, so a 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 verb 'List', the resource 'members of a HAOps project', and includes additional details 'with their roles and activity stats'. It distinguishes from sibling tools like haops_add_member and haops_update_member_role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like haops_add_member or haops_update_member_role. No mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the operations without mentioning side effects, permissions, or error states. It lacks transparency.
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 concise (two sentences) and front-loaded with the verb and resource, but it could include more specific details to improve informativeness without bloating.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, multiple actions), the description is too brief. It omits return values, error handling, and action-specific behavior, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3; the description adds no extra meaning beyond the schema, but the schema itself is clear. No additional parameter context is given.
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 it manages Git repositories with explicit actions (list, get, create, update, delete) and ties it to a HAOps project, distinguishing it from sibling tools that operate on other entities.
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?
No explicit guidance on when to use this tool versus alternatives; usage is implied by the action parameter, but no context about prerequisites or when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states the core behavior. It does not disclose required permissions, side effects, or scope (e.g., whether it marks messages across all channels or just a single conversation). The description is under-informative 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 sentence with no redundancy. It is efficient and front-loaded.
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 low complexity, the description is adequate but lacks details like idempotency or confirmation of action. With no output schema, some return behavior context would be helpful.
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 baseline is 3. The description adds no additional meaning beyond the schema. It does not explain how the parameters relate or provide context for the verbose option.
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 ('mark') and the resource ('all direct messages from a specific user as read'). It is specific and distinguishes well from sibling tools like haops_mark_notification_read or haops_send_dm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context. Usage is only implied by the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions marking as read but doesn't disclose mutability, reversibility, or permissions; the behavioral details are minimal.
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 unnecessary words; perfectly concise.
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 mutation with no output schema and two documented parameters, the description is minimally adequate but lacks broader context like state change implications.
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 descriptions for both parameters; the tool description adds no additional meaning beyond what is already 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 verb 'mark' and the resource 'notification', distinguishing it from siblings like haops_list_notifications and haops_mark_dm_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; no when-not or alternative tools mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only says 'Update... fields' without mentioning side effects (e.g., notifications, permission requirements, or that unspecified fields remain unchanged). The 'verbose' parameter behavior is only defined in the schema, not in the description.
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 a single, efficient sentence. It is concise but lacks front-loading of critical information. However, it is not overly verbose and each phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, many optional) and lack of output schema, the description is minimal. It does not explain return value, default behavior, or any prerequisites. Sibling tools exist for related actions, so more guidance would be beneficial.
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 has 100% coverage with descriptions for all 9 parameters. The description adds no additional meaning beyond listing the fields. It does not explain relationships or constraints (e.g., status transition rules).
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 it updates helpdesk ticket fields and lists the specific fields (status, priority, category, assignee, tags). It distinguishes from sibling tools like haops_create_ticket and haops_close_ticket by specifying it's for triage and management of existing tickets.
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?
It implies use when modifying ticket fields, but lacks explicit guidance on when to use alternatives (e.g., haops_close_ticket, haops_reply_ticket). The phrase 'Used for triage and management' provides some context but no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It reveals cascade deletion behavior but omits critical details such as irreversibility, required permissions, side effects on associated data, and whether the operation can be undone. This is insufficient 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 extremely concise: a single sentence with two clauses. It is front-loaded with the action and resource, then provides the critical conditional behavior. No superfluous 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?
With no output schema, the description should cover what the tool returns or what happens after deletion. It does not mention response format, success indicators, or error conditions. The description adequately covers the core purpose and a key behavioral condition, but leaves the agent uninformed about the outcome.
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 100% coverage of parameters. The description adds meaningful context to the 'confirm' parameter by explaining its role in cascade deletion. This goes beyond the schema description, which only says 'Set to true to confirm cascade deletion...' The other parameters (projectSlug, moduleId, verbose) are not further clarified, but the schema already adequately describes them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete a module) and the resource (HAOps project module). It is distinct from other delete tools by specifying the entity type, but does not explicitly differentiate from sibling delete tools like haops_delete_feature or haops_delete_issue.
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 provides a key conditional usage guideline: requires confirm=true if module has child features for cascade deletion. However, it does not give guidance on when to avoid using this tool (e.g., if intending to archive rather than delete) or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions output content ('who changed what and when') but lacks disclosure of behavioral traits such as read-only nature, authentication requirements, rate limits, pagination, or result ordering.
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-load the purpose and key details. No redundant or unnecessary information. Efficiently conveys 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 read tool with three required params and no output schema, the description adequately covers what the tool does and what output to expect. It could mention default behavior or sorting but is largely 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 descriptions cover all three parameters with clear definitions (projectSlug, entityType enum, entityId UUID). Description adds minimal extra meaning beyond confirming entity types, which are already in the schema. Baseline of 3 for 100% schema coverage 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?
Clearly states verb 'Get', resource 'activity log', and scope 'for a specific entity (Module, Feature, or Issue) in a HAOps project'. Distinguishes from sibling get_* tools by specifying the exact resource and entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like haops_get_audit_log or other get_* tools. Does not mention when not to use it or what to use for broader activity tracking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions retrieving information but lacks details on idempotency, permissions, rate limits, or side effects. The description is minimal and relies on the agent inferring that it is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource. It is concise and avoids unnecessary words. However, it could be slightly expanded to include more context without sacrificing 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?
No output schema is provided, so the description should explain what is returned. It mentions 'detailed information, including metadata and entity linkage', but this is somewhat vague. For a simple retrieval tool, this may be adequate, but it could be more specific about the structure of the response.
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 the parameters are fully described in the schema. The description does not add significant meaning beyond what the schema provides (e.g., 'projectSlug' and 'discussionId' are not elaborated further). Baseline 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 action ('Get detailed information'), the resource ('a specific discussion thread'), and specifies what is included ('metadata and entity linkage'). This distinguishes it from sibling tools like haops_list_discussions (list) and haops_search_discussion (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs details about a specific discussion, but it does not explicitly state when to use this tool versus alternatives like haops_list_discussions or haops_search_discussion. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'shows exactly what changed' but does not disclose read-only nature, permission requirements, response format, or any side effects. The description is minimal in behavioral detail.
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 with no wasted words. Front-loaded with the action and immediately gives context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description lacks completeness. It does not describe what the diff output contains, any pagination, or format. For a data retrieval tool, more context is needed.
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% as each parameter has a description. The tool description does not add any additional meaning beyond what is already in the schema, so baseline 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 verb ('Get'), the resource ('diff output for a specific git commit'), and the purpose ('Essential for code review'). It distinguishes from siblings like haops_get_branch_diff and haops_git_commit_log.
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 code review but provides no explicit when/when-not to use this tool versus alternatives like haops_get_branch_diff. No exclusions or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it returns matching messages but lacks details on pagination, limits, permissions, or error behavior. For a search tool, this is insufficient 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?
Two short, efficient sentences with no excess words. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 required params, the description is minimal. It does not explain return format, error cases, or how to effectively use the tool. Sibling differentiation is thin.
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 parameters are fully described in the schema. The description does not add extra meaning beyond the schema (e.g., query format, how to derive projectSlug/discussionId). Baseline 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 verb 'Search messages within a specific discussion thread' and the resource 'messages within a discussion', distinguishing it from siblings like haops_get_discussion (thread metadata) or haops_get_discussion_messages (all messages).
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 searching messages in a thread but does not explicitly state when to use this tool vs alternatives like haops_get_discussion_messages or haops_search_help. No when-not or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It only mentions markdown conversion, omitting details on persistence, notifications, permission requirements, rate limits, or error conditions, leaving significant behavioral gaps.
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: two sentences that front-load the primary action and add a key formatting detail. Every word earns its place without fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no output schema, and no annotations, the description is insufficient. It lacks context about return values, error handling, member validation, message length limits, or any operational constraints, making it incomplete for a reliable AI invocation.
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 a note about markdown conversion, but this largely restates what is already in the content parameter's schema description, adding no new parameter-level meaning.
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 'Send a direct message to a user in a HAOps project,' using a specific verb and resource. It distinguishes from sibling tools like haops_post_message by specifying 'direct message' to a user rather than a channel.
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 does not explicitly state when to use this tool versus alternatives like haops_post_message. It implies direct messaging by saying 'to a user,' but lacks clear guidance on when not to use it or what distinguishes it from channel messaging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It does not disclose what happens to the old content, whether updates are partial or full, required permissions, or the response format. This leaves the agent underinformed.
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 sentence with the verb first, no wasted words. It is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 optional parameters and no output schema or annotations, the description lacks important context such as how partial updates work, what response to expect, and behavioral details. It is too brief for a mutation tool with multiple options.
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 5 parameters, so the description adds no additional meaning beyond the schema. Baseline score of 3 is appropriate as the schema 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 verb 'Update' and the resource 'existing help article', and specifies the method 'by slug'. This distinguishes it from sibling tools like haops_create_help_article and haops_delete_help_article.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an existing help article needs modification but does not provide explicit guidance on when to use this over alternatives, nor does it mention prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose all behavioral traits. It mentions accepting base64 image data and returning a URL, but does not specify permissions, rate limits, side effects (e.g., whether it replaces existing images), or error conditions. The description is minimal.
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-loading the purpose and key details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a file upload tool with no output schema, the description explains the return value (attachment record with URL). It covers the main workflow, though it could mention that the image is stored and associated with the section. Overall sufficient for a simple upload.
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 clear descriptions for all 7 parameters. The description adds context about base64 encoding and the return value but does not provide parameter-specific meaning beyond the schema. Baseline 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?
Description clearly states the verb ('upload'), the resource ('image to a documentation section'), and the expected return ('attachment record with a URL for embedding'). This distinguishes it from sibling 'haops_upload_help_image' which targets help articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs siblings like 'haops_upload_help_image'. The description implies documentation sections but does not state when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 mentions email sending conditional on message but fails to indicate side effects (e.g., ticket irreversibility, required permissions, or status transitions). The description is minimal for a mutating 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?
Two concise sentences with no redundancy. Every word adds value. Front-loaded with the main action.
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's complexity is moderate with 5 parameters and 3 required. The description covers the primary effect but omits when to use versus other ticket tools, any prerequisites, and expected response format. Lacks completeness despite good schema coverage.
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%; all parameters are documented in the schema. The description adds context for the resolutionNote parameter by linking it to email sending, but overall adds limited extra 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 clearly states the tool's purpose: 'Resolve or close a helpdesk ticket' with optional messaging. This verb+resource combination distinguishes it from siblings like haops_reply_ticket (reply without closing) and haops_update_ticket (update without closing).
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 usage context (optional final message triggers email) but lacks explicit when-to-use or when-not-to-use guidance. It does not contrast with alternative tools like haops_reply_ticket or haops_update_ticket for non-closing scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the creation action and uniqueness, but fails to disclose behavior on duplicate artifact types (e.g., does it error or silently overwrite?), permissions needed, or side effects. This is insufficient 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?
Two concise sentences, each adding value: first states purpose, second adds a key constraint. No unnecessary words.
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 5 parameters and no output schema, the description is minimal. It covers basic purpose and a constraint but lacks usage guidance, error behavior, or description of return value. Adequate but not complete for a creation 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%, so baseline is 3. Description adds no additional meaning beyond the schema; enum values for type and details on the 'verbose' parameter are already clear from schema 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?
Description clearly states 'Create a new documentation artifact for a project', with a precise verb and resource. The constraint 'One artifact per type per project' differentiates it from sibling tools like haops_create_doc_section or haops_update_doc_artifact.
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?
Description implies creation of new artifacts and uniqueness constraint, but does not explicitly guide on when to use this vs haops_update_doc_artifact or how to handle duplicate types (error vs overwrite). No alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool deletes an artifact and its sections but does not disclose if the action is irreversible, requires special permissions, or has cascading effects. For a destructive operation, more behavioral context is needed.
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?
Single sentence is concise and directly states the action. Could benefit from a brief additional context, but no wasted words. Front-loading is good as the verb 'Delete' appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with no output schema and 3 well-documented parameters, the description covers the essential information. Minor gaps like irreversibility or permissions prevent 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?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter.
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 (delete), the target resource (documentation artifact), and scope (all its sections). It distinguishes itself from sibling tools like haops_delete_doc_section which deletes only a single section.
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?
No explicit guidance on when to use this tool versus alternatives like haops_delete_doc_section. However, the purpose is clear enough that an agent can infer usage context, but explicit when-to-use or when-not-to-use would improve score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose side effects, error handling, permission requirements, or behavior on missing features. It only describes the return fields.
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, front-loaded with purpose, no redundant information. Every word is necessary.
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?
With no output schema, the description compensates by listing response fields. However, it lacks details on error handling, permissions, or edge cases, which are important for a robust understanding.
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 basic descriptions. The description adds value by detailing the response fields but does not elaborate on parameters 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 gets full details for a single feature and lists included fields (title, status, priorities, etc.), distinguishing it from listing or updating tools.
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 viewing feature details but provides no explicit when-to-use or when-not-to-use guidance, nor mentions alternatives like haops_list_features or haops_update_feature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. Only states the return structure, missing details like read-only nature, authentication requirements, rate limits, or empty result behavior.
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 efficient sentences, no filler. Front-loaded with core purpose and structure.
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?
Describes output as 'Module→Feature→Issue tree', but lacks details on pagination, sorting, depth, or response format. Without output schema, more completeness needed.
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?
All 4 parameters have schema descriptions (100% coverage). The description adds the context of optional filters and tree output, but no new semantics beyond 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?
Clearly states 'Get a structured (nested) view of the project work hierarchy' with specific verb and resource. Distinguishes from flat list siblings by mentioning 'Module→Feature→Issue tree'.
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?
Implies usage for display purposes with 'pre-organized for display', but no explicit when-to-use or alternatives guidance. Among many list tools, a note about preferring this over multiple list calls would elevate it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It states the tool lists DMs with specific data, but does not disclose traits like read-only nature, authentication needs, rate limits, or pagination. 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?
The description is a single, well-structured sentence with no extraneous words. Every part adds value.
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 list tool with no output schema, the description provides some return value info (unread counts, last message previews) but omits details like pagination, ordering, or response format, leaving gaps for agent comprehension.
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 covers the parameter with a description. The tool description adds no additional meaning beyond referencing 'in a project', so it meets 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 states the tool lists all direct message conversations, including unread counts and last message previews, distinguishing it from sibling tools like haops_get_dm_history (which gets history of a specific DM) and haops_send_dm.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like haops_get_dm_history or haops_mark_dm_read, missing explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns MR title, status, branches, author, and timestamps, implying read-only behavior. However, it does not mention pagination, ordering, or any side effects. With annotations absent, this is adequate but not thorough.
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?
Two sentences, front-loaded with purpose, followed by return information. No unnecessary words. While efficient, it could be slightly more concise, but it is 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?
Given the tool's complexity (5 parameters, no output schema, no annotations), the description covers the core purpose and return fields. It lacks a mention of ordering or pagination defaults, but the schema includes the limit parameter. Almost complete for a list 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?
The input schema has 100% description coverage, with each parameter well-documented. The description adds 'with optional filters' but does not provide additional meaning beyond the schema. Baseline 3 is appropriate since 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 verb 'List', the resource 'merge requests', and the scope 'for a project with optional filters'. It also specifies the returned fields (title, status, branches, author, timestamps). This distinguishes it from sibling tools like haops_list_issues or haops_list_tickets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned. The description simply states what the tool does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden. It only states it returns summaries with counts, but does not disclose any behavioral traits such as rate limits, authentication requirements, or side effects (though likely read-only). The description is minimal.
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 sentence that directly states the purpose and output, with no wasted words. It is appropriately sized and front-loaded with the key action.
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 4 parameters fully described in schema and no output schema, the description is minimal but covers the basic idea. However, it lacks explanation of what 'recent' means (time window, ordering) and could benefit from mentioning default sorting or pagination behavior, making it slightly 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%, so the schema already documents all parameters (limit, runner, environment, projectSlug). The description adds no additional meaning beyond what is in the schema, resulting in a 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 states 'List recent test runs for a project' with a specific verb and resource, and adds 'Returns run summaries with pass/fail counts' which clarifies the output. This clearly distinguishes it from siblings like haops_list_tests (test cases) and haops_report_test_run (creating a run).
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 listing test runs, but provides no explicit guidance on when to use this tool versus alternatives (e.g., haops_list_test_suites, haops_get_test_health) or any when-not situations. It is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It only states the action and a constraint, but omits details like required permissions, immediate effects, reversibility, or error scenarios. This is insufficient 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?
Two sentences, no fluff. The constraint is front-loaded. Every word serves a purpose.
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 no output schema and no annotations, the description minimally covers the tool's purpose and a key constraint. However, it lacks details on output, permissions, and side effects, which would be helpful for a mutation 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%, so the schema already documents each parameter. The description adds no extra meaning beyond what's in the schema, so 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 action: update a project member's role, and explicitly notes a critical constraint (cannot change owner role). This distinguishes it from sibling tools like haops_add_member and other update tools.
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 role changes, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., haops_add_member for adding, haops_list_members for viewing). The 'Cannot change the owner role' constraint is stated, but no exclusions or context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 disclosing behavioral traits. It does not state whether the tool is read-only, if it has side effects, or if it requires specific permissions. It only vaguely mentions the output format (findings with severity and recommendations) but lacks details on rate limits, error behavior, or what constitutes 'stale' or 'inconsistent.' This is insufficient for safe and accurate agent invocation.
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, consisting of two sentences with no wasted words. The first sentence immediately states the action and scope, and the second describes the output format. It is front-loaded and earns its place by being both brief and informative, making it easy for an AI agent to quickly parse the tool's core function.
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 5 parameters (none required) and no output schema, the description is somewhat brief. It identifies the type of output (findings with severity) but does not provide examples, structure, or guarantee the completeness of the returned data. For a diagnostic tool, more detail on the format and utility of findings would be beneficial for context. However, the parameter descriptions in the schema partially compensate, resulting in an adequate but not comprehensive description.
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 parameter descriptions with 100% coverage, including enum values for verbosity and entityType, and defaults. The description does not add any new semantic meaning beyond what is in the schema. For instance, it does not clarify how parameters interact or the exact impact of verbosity levels. Given high schema coverage, a baseline score of 3 is appropriate, as the description is not needed for parameter comprehension but also does not enhance 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 states the action 'Run health checks on work entities' and specifies the purpose: 'detect stale, inconsistent, or problematic states.' It also mentions the output 'findings with severity and recommendations.' This verb-resource pair distinguishes it from sibling tools, which are primarily CRUD or retrieval operations, making the tool's unique purpose evident.
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 the tool is for diagnostic purposes but provides no explicit guidance on when to use it versus alternatives. There is no mention of prerequisites, scenarios, or exclusion criteria. While the purpose is clear, the lack of contextual usage instructions leaves room for ambiguity, especially given the presence of similar health check tools like haops_get_protocol_health.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states the status change to 'closed'. Does not disclose permissions, reversibility, or other side effects, which is insufficient for a mutation tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two short sentences with no wasted words. The key information is front-loaded.
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 mutation tool with fully documented parameters and no output schema, the description covers the action and outcome adequately. However, it could mention the response format or any prerequisites.
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 schema already describes all parameters. Description adds no additional meaning to parameters beyond what schema provides, so 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?
Description clearly states the action (close), resource (merge request), and outcome (status set to 'closed'). Distinguished from merging by stating 'without merging', contrasting with sibling haops_merge_merge_request.
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?
Implies usage when needing to close a merge request without merging, but does not explicitly mention alternatives like haops_merge_merge_request or haops_reopen_merge_request, or provide 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a key side effect: deleting the channel also deletes all discussions. However, it lacks information on irreversibility, authorization requirements, or other potential impacts, leaving the agent underspecified for safe invocation.
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: two sentences that front-load the primary action and then add the critical side effect. Every word contributes value, with zero 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 destructive tool with no output schema, the description adequately covers the core action and the cascade deletion of discussions. It could be improved by mentioning return value or permission requirements, but it is sufficiently complete for an agent to understand the primary consequence.
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 the schema already documents all three parameters (verbose, channelId, projectSlug). The description does not add any additional meaning or context for the parameters beyond what is in the schema, earning the baseline score.
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 ('Delete a channel') and the resource ('from a HAOps project'), and specifies that all discussions in the channel are also deleted. This differentiates it from sibling tools like create or update channel, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives, nor does it mention when not to use it (e.g., if discussions should be preserved). No explicit alternatives or context for the appropriate situation are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that deleting a section cascades to all its articles, and that the action is restricted to admins. However, it does not mention that the action is irreversible, whether dependencies exist, or what happens on failure. This is adequate but not fully 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 extremely concise: two short sentences that immediately communicate the core action, scope, and access restriction. Every word adds value, and there is no fluff. It is front-loaded with the most critical 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?
Given the low complexity (two parameters, no output schema, no nested objects), the description adequately covers the primary behavior. It states that the section and all its articles are deleted and that admin privileges are required. However, it could be improved by mentioning that the action is irreversible and suggesting that users should verify the section slug beforehand (e.g., via haops_list_help_sections). Still, it is largely complete for its simplicity.
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 does not add any information about the parameters beyond what the schema already provides. The `verbose` parameter's purpose is fully explained in the schema, and `sectionSlug` is self-explanatory. No additional context is provided.
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 ('Delete'), the resource ('help center section'), and the scope ('and all its articles'), with a specific access requirement ('Admin-only'). It distinguishes itself from sibling tools like haops_delete_help_article by focusing on sections and their contained articles.
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 does not provide any guidance on when to use this tool versus alternatives. There is no mention of prerequisites, potential side effects, or scenarios where other tools (e.g., deleting individual articles first) might be preferred. The only hint is 'Admin-only', which implies authorization but not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that behavior differs by context (protocol vs MCP server) and mentions return format. However, it does not explicitly state that the operation is read-only or non-destructive, nor does it mention any prerequisites or limitations.
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: two sentences that front-load the purpose and immediately provide contextual distinctions. There is zero redundancy or unnecessary 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?
Given the tool's simplicity (2 parameters, no output schema), the description covers the key behavioral differences and return types. It lacks mention of error handling or rate limits, but for a download operation this is acceptable.
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 clear descriptions for both parameters. The description adds no additional meaning beyond what the schema already provides, so baseline 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 verb 'Download/view' and the resource 'update artifact'. It distinguishes between two contexts (protocols and MCP server) with specific return behavior, making it easy to understand the tool's core function.
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 does not provide any guidance on when to use this tool versus alternatives (e.g., haops_list_updates). No explicit when-to-use or when-not-to-use criteria are given, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It correctly implies a read-only list operation but does not disclose potential rate limits, pagination details beyond the schema, or any side effects. The description is minimal.
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 verb 'List' and resource 'issues'. Every word is useful with no redundancy, achieving high efficiency.
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?
With no output schema, the description compensates by listing the returned fields. It covers all key aspects: purpose, filters, and output. Missing explicit mention of required projectSlug, but schema covers that. Overall adequate for a simple list 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%, so baseline is 3. The description lists filter parameters (featureId, type, status, priority, assignee) but adds no new meaning beyond what is in the schema. It does mention returned fields, which relates to output, not parameter semantics.
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 issues in a HAOps project with optional filters, listing specific filter fields and return fields. This distinguishes it from sibling list tools like haops_list_features and haops_list_tickets.
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 listing issues with filters but does not provide explicit when-to-use or when-not-to-use guidance or alternatives. It relies on the tool name and context to differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the transparency burden. It states the tool lists versions and returns specific fields, implying read-only operation. However, it does not disclose ordering, pagination, limits, or behavior when no versions exist. This is basic 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 efficient sentences with no wasted words. The first sentence states the primary purpose, and the second lists return fields. Front-loaded and to the point.
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 two simple parameters, no output schema, and complete schema descriptions, the description covers the essential functionality and return data. Minor gaps remain (e.g., ordering, pagination) but it is largely sufficient for an agent to use the 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 descriptions for both parameters (role and projectSlug). The description adds no additional meaning beyond what the schema provides, so it meets the baseline for high 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 clearly states it lists all versions of a work protocol for a specific agent role, and enumerates the returned fields (version numbers, timestamps, change summaries, who updated). This distinguishes it from sibling tools like haops_read_protocol (reads current protocol) and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like haops_read_protocol or haops_get_protocol_health. It does not mention prerequisites, when not to use, or how the returned versions relate to other protocol operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 'update' (mutation) but does not mention whether updates are partial or full, idempotency, permissions required, or any side effects. This leaves important gaps for agent understanding.
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 that are front-loaded with what the tool does and followed by a specific use case. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not mention return values or what the tool returns (e.g., updated discussion object vs. summary). Given no output schema and no annotations, this omission is significant for agent planning. Also lacks guidance on typical parameter combinations.
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 detailed descriptions for all 10 parameters. The description adds high-level grouping (title, status, etc.) and associates status with resolving/closing, but this adds only marginal value beyond the schema's 'e.g., resolved, closed' hint. Baseline 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 verb 'Update' and resource 'discussion properties', lists specific properties (title, status, priority, assignment, locking, pinning), and distinguishes from siblings like create and delete by focusing on modification.
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 says 'Use this to resolve/close discussions or change metadata,' providing clear context for when to invoke the tool. It lacks explicit when-not-to-use statements but implies separation from create/delete tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 cascade deletion behavior and the need for confirmation, but does not mention irreversibility, required permissions, or error handling. The behavioral disclosure is partial.
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-loading the core action. Every sentence adds value without 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 no output schema, the description does not explain return values or success/failure signaling. It covers the cascade condition but lacks details on what happens if confirm is false when children exist, or what the output looks like.
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 baseline is 3. The description reinforces the confirm parameter's role in cascade deletion but does not add significant new 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a feature from a HAOps module', which is a specific verb+resource. It differentiates from sibling tools like haops_create_feature or haops_delete_module by focusing on feature deletion.
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 mentions the condition for cascade deletion (confirm=true when child issues exist) but does not provide explicit when-to-use or when-not-to-use guidance relative to alternatives. It lacks context for choosing this tool over related delete tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 full burden. It indicates read-only behavior by 'shows all changes', but does not detail error handling for non-admin users, pagination behavior, or data scope beyond 'all changes across the platform'.
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 contains no redundant information. Every word serves a purpose.
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?
No output schema is provided, yet the description does not hint at the return format or structure of the audit log entries. Pagination is implied by schema but not mentioned in description. Adequate but not thorough for a tool with no output 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?
Input schema has 100% parameter description coverage (page, limit, action, entityType). The description only says 'with filters' without adding extra meaning or context beyond what the schema already provides. 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?
The description clearly states the tool retrieves 'system-wide audit log' with 'filters', specifying it's 'admin only'. It distinguishes from sibling tools like haops_get_activity by indicating system-wide scope.
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 mentions 'admin only' as a prerequisite but does not explicitly contrast with similar tools like haops_get_activity or specify when to use this tool instead of others. Usage context is implied but not fully elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description indicates read-only behavior ('Get full details'). Lists included fields but omits additional behavioral traits like auth requirements, error states, or output format. Adequate but minimal.
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?
Single concise sentence (15 words) front-loading the action and resource. Efficient, though could include a brief note on when to use without significant bloat.
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 no output schema, description lists return fields (title, status, etc.) which is helpful. For a simple retrieval tool, this is reasonably complete. Lacks error or existence guarantees but acceptable.
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 parameters documented. Description does not add new meaning beyond the schema descriptions of 'UUID of the module' and 'The project slug (URL identifier)'. Baseline 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?
Clearly states 'Get full details for a single module' with specific fields listed (title, status, priority, etc.). Distinguishes from sibling tools like list_modules (list all) and update_module (modify).
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?
Implies usage for retrieving details of a single module, but does not explicitly contrast with list_modules or other get-sibling tools. No when-not or alternative guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose permissions, side effects, or any behavioral traits beyond the listing action. It is a read operation but not stated.
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 concise sentences, front-loaded with the action and key details, no unnecessary words.
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?
No output schema present; description lists artifact types but does not specify the return format (e.g., list of strings or objects), leaving some ambiguity.
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 has 100% coverage with a single parameter described; description adds no further meaning beyond 'the project slug'.
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 it lists documentation artifacts for a project and enumerates the artifact types, distinguishing it from sibling list tools.
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?
No explicit guidance on when to use this tool vs alternatives; context is implied but lacks exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It implies a read-only operation but does not explicitly state safety, side effects, or any constraints, leaving the agent uninformed about potential behaviors.
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 sentence, front-loaded with the action and resource, with zero wasted words. It earns its place entirely.
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 low complexity (0 params, no output schema), the description is adequate but not rich. It does not elaborate on return format, scope of 'all projects', or any prerequisites, leaving some context 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 input schema has zero parameters with 100% coverage, so the description adds no param info, which is appropriate. Baseline score of 4 is justified as no additional meaning 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 'List all projects in HAOps' clearly states the verb (list) and resource (projects), distinguishing it from sibling list tools for other entities.
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 provides a clear intended use (listing projects) but lacks explicit when-to-use or alternatives guidance. However, given the simplicity of a parameterless list, the context is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It implies a read-only operation by its nature ('List'), but does not explicitly state that it is non-destructive or safe. It also does not mention any authorization requirements, rate limits, or 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 concise with two sentences. The first sentence states the purpose directly, and the second adds relevant context. Every word earns its place; no fluff.
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 description explains the tool's purpose and what role templates are, but lacks details on output format, pagination, sorting, or whether the list includes both system and custom templates (though implied). For a simple list tool, it is adequate but not fully comprehensive.
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 baseline is 3. The description adds no additional parameter guidance beyond what is already in the schema (e.g., 'Free-text search across name + description' and 'Filter by base role bucket'). It does not elaborate on how to use them 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 clearly states the verb 'List' and the resource 'agent role templates', and explains what a role template is and its purpose. It distinguishes from sibling tools like haops_create_role_template or haops_read_role_template by its focus on listing.
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 mentions 'System templates are seeded; admins may publish project-specific custom templates,' providing context on what will be listed. However, it does not explicitly advise when to use this tool versus alternatives like haops_read_role_template or haops_search_help, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It mentions pagination but does not disclose rate limits, authentication needs, or behavior when no results are found. For a read-only listing tool, the disclosure is minimal.
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 concise sentences with no redundancy. Core purpose and key behavioral trait (paginated results) are front-loaded.
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 8 parameters, no annotations, and no output schema, the description is adequate but minimal. It mentions pagination but does not emphasize the required projectSlug or summarize available filters. The schema fully covers parameters, so completeness is average.
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 the description adds little beyond stating 'optional filters'. All parameter descriptions are in the schema, and the description does not clarify parameter interactions or prerequisites.
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?
Description clearly states the tool lists helpdesk support tickets for a specific project, with optional filters and pagination. It distinguishes from sibling tools like haops_create_ticket, haops_get_ticket, and haops_close_ticket.
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 viewing tickets with filters but lacks explicit guidance on when to use this tool versus alternatives like haops_get_ticket or haops_search_discussion. No exclusions or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 behavioral traits. It only states the actions (list, add, revoke) without explaining authentication requirements, side effects, or what happens on revocation. For a tool modifying SSH keys, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with purpose, and contains no redundant information. Every word is meaningful.
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?
With no output schema, the description should explain return values and behavior. It mentions the compact summary vs full response via the verbose parameter but omits detailed response structure, error handling, or prerequisites. While the schema covers parameters, the tool description lacks completeness for a management tool with multiple actions.
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 with descriptions for all five parameters. The description adds context about self-service and Git access but does not enhance parameter-level meaning beyond what the schema provides. Baseline 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 verb 'Manage' and specifies the resource 'SSH keys for HAOps Git access', listing the supported actions (list, add, revoke). This distinguishes it from sibling tools that deal with other entities like members, modules, or tickets.
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 mentions 'Agents can use this to self-service their SSH keys for git push access', which gives clear context and a specific use case. However, it does not provide explicit guidance on when not to use or mention alternatives, though sibling tools offer no SSH key management alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that author is auto-populated and tag restrictions exist, but does not mention idempotency, side effects, or what happens on conflict. No annotations are provided, so description carries the burden; it's 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 with no redundancy. First sentence states purpose, second adds critical usage constraints. 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?
With 6 parameters, 5 required, and no output schema, the description covers tag restrictions and author but omits return value format and any edge-case behavior (e.g., duplicate appends). It is minimally adequate but incomplete for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions. The description adds value by explaining auto-populated author and tag-role mappings beyond the schema's enum list. The schema already documents all parameters, so baseline 3; the added context justifies a 4.
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 'Append a tagged log entry to entity agent memory' with specific verb and resource. However, it does not explicitly differentiate from siblings like haops_read_memory or haops_consolidate_memory, but the unique behavior (append with tags) is clear.
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 tag restrictions based on agent role (e.g., 'dev can use: context, decision, progress, issue; qa: review, issue; architect/admin: all tags'), which guides when to use which tags. Lacks when-not-to-use guidance but offers clear context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses what claiming does (marks in-progress, assigns takenBy) and the force parameter requires PM+ role. However, it does not explain unclaim effects (e.g., resetting status or removing takenBy) or permissions for regular claiming. Some behavioral aspects are missing.
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 primary action, and no extraneous information. Every sentence adds value: first states purpose, second explains 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?
No output schema exists, but the verbose parameter hints at response types. The description covers purpose, primary effects, and key parameter constraints. However, it omits details on unclaim behavior and permissions for the basic claim action. Still, it is largely complete for a straightforward claim/unclaim 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%, so baseline is 3. The description adds context for the force parameter (requires PM+ role) and notes default action is claim, but this information is already in the schema descriptions. The tool description does not significantly enhance parameter understanding 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 uses a specific verb ('claim or unclaim') and resource ('helpdesk ticket'), and distinguishes it from sibling claim tools (haops_claim_feature, haops_claim_issue, haops_claim_module) by specifying 'helpdesk ticket'. It also explains the side effects (marks as in-progress, assigns takenBy fields).
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 helpdesk tickets via resource naming, but does not explicitly state when to use this tool versus alternatives like haops_claim_issue or haops_claim_feature. No prerequisites or exclusions are mentioned, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states export but does not disclose read-only nature, permissions needed, side effects, or rate limits. For a no-annotation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. Front-loaded with verb and resource, then 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 simple export tool, description covers what is exported and format. Lacks mention of return format details or error conditions, but adequate given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, but description adds value by explaining that the export includes suite config and all test definitions, which is not in 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?
Clearly states verb 'Export', resource 'test suite', output format 'JSON bundle', and purpose 'cross-project sharing'. Includes what is bundled, distinguishing from sibling import tool.
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?
Implies usage for exporting test suites, but no explicit guidance on when to use versus alternatives like import or other export tools. No exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the ZIP is saved to a local temp file and returns a path, but it does not cover side effects (e.g., overwrites, auth requirements) or behavior beyond basic output. With no annotations, more behavioral detail would be helpful.
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 three sentences, front-loaded with the key purpose, and contains no fluff. Every sentence adds value.
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 high parameter count (29) and absence of output schema, the description adequately explains the output and purpose. It could be improved by mentioning error conditions or required permissions, but is fairly complete for its complexity.
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 all parameters described. The description adds no extra meaning beyond what the schema already provides, so baseline score 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 generates a Developer Onboarding Kit ZIP, listing specific contents (memory files, agent definitions, project configuration). It distinguishes this from other sibling CRUD tools by focusing on generation rather than management.
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 the tool is for onboarding new developers but does not specify when to use it versus alternatives, nor does it mention prerequisites or when not to use it. Usage is implied by context but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states 'retrieve' and 'read', implying read-only. Does not disclose pagination behavior, ordering, or any side effects. Lacks depth for a mutation-free context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, zero wasted words. Highly concise and clear.
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?
Tool is simple; description covers core purpose. Missing details on pagination behavior and return format, but schema provides parameter info. Without output schema, description is nearly 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?
Input schema covers 100% of parameters with descriptions. Description adds no extra meaning beyond schema. Baseline score for high coverage is 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?
Description clearly states verb 'retrieve', resource 'direct message history', and target 'with a specific user'. Distinguishes from siblings like haops_send_dm and haops_list_dm_conversations.
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?
Explicitly says 'Use this to read DM context before replying', providing a clear scenario. However, doesn't mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries full burden. Lists returned fields but omits behavioral details like permissions, rate limits, error handling, or caching. 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?
Single sentence, front-loaded, efficient. Every word adds value 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 get operation with two parameters and no output schema, description adequately covers purpose and returned fields. Could mention error cases or output format, but not necessary.
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 clear parameter descriptions. Description adds no additional parameter meaning beyond listing returned fields. Baseline 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?
Clearly states 'Get full details for a single issue' and lists specific fields. Distinguishes from siblings like 'haops_list_issues' (list) and 'haops_get_feature' (different resource).
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?
Implies use for full details of one issue, but lacks explicit when/when-not guidance. No mention of alternatives or when to use other tools like list_issues for summary data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description implies a read-only operation by returning commit history, but it does not explicitly state that the tool is non-destructive, nor does it mention authentication, rate limits, or pagination behavior. It adds value by listing returned fields but lacks comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, directly states the purpose, returned data, and a key feature (multi-repo support). Every word is necessary, and it is front-loaded with the main action.
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 five parameters and no output schema, the description covers the essential purpose and a notable differentiator (multi-repo). The schema handles parameter details. However, it does not mention that the tool is read-only or provide error scenarios, though these are less critical for a retrieval 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%, so the schema already documents all five parameters. The description adds minimal supplementary meaning beyond summarizing the schema (e.g., 'Supports multi-repo projects via repositoryName'). It does not clarify parameter types, defaults, or constraints beyond what is 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 retrieves recent commit history from a project's Git repository and lists the returned fields (SHA, author, date, message). It also mentions support for multi-repo projects via repositoryName, which distinguishes it from sibling tools like haops_git_commit_diff.
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 does not explicitly state when to use this tool versus alternatives such as haops_git_commit_diff or haops_git_list_files. The context of multi-repo support provides some guidance, but no when-not-to or explicit alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses return structure but lacks details on behavior like pagination, recursion depth (likely only immediate children), performance, or auth requirements. No contradictions with 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?
Two concise sentences with no fluff. Information is front-loaded and every sentence adds value. Efficient and clear.
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 no output schema, description explains return fields (type, name, SHA). Could improve by specifying it lists immediate children only and clarifying path format. Mostly complete for a listing 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%, so baseline is 3. Description adds minimal extra meaning: 'Supports multi-repo projects via repositoryName' echoes the schema. No additional semantics for ref, path, or projectSlug beyond what schema provides.
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 'List' and the resource 'files and directories in a project's Git repository at a given path'. It mentions return values (type, name, SHA) and distinguishes from sibling tools like haops_git_read_file by focusing on listing.
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 listing directory contents but does not explicitly state when to use this tool versus alternatives like haops_git_commit_log or haops_git_read_file. No exclusions or context about when not to use it are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses the creation behavior (creating TestRun and TestResult records) but lacks details on side effects, idempotency, authentication, or error states. It 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 two sentences, front-loaded with purpose, and contains no unnecessary words. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, nested objects, no output schema), the description is insufficient. It doesn't explain return values or how summary/results relate, and lacks details on behavior like overwriting or partial failures.
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 baseline is 3. The description adds no extra meaning beyond the schema; it summarizes the action but doesn't clarify parameter relationships or defaults. It does not compensate for any gaps.
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 reports test results to HAOps by creating a TestRun with TestResult records. It uses specific verbs and resources, and the mention of manual vs automatic reporting distinguishes it from sibling tools like haops_list_test_runs.
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 says it is 'Used by agents to manually report results,' contrasting with automatic reporters like Jest/Playwright. This gives clear when-to-use guidance, though it doesn't explicitly state when not to use it or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It states it uploads (mutation), requires admin privileges, accepts base64 data, and returns an attachment record with a URL. This is clear and adequate, though it does not mention potential side effects or limits.
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 only three sentences, no redundant words, and front-loads the main purpose. Every sentence adds value without being verbose.
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 action, input format, access restriction, and return value. Without an output schema, it provides enough context for a simple upload tool. However, it does not differentiate from similar sibling tools or mention any limitations (e.g., file size), leaving some uncertainty.
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 the baseline is 3. The description does not add significant meaning beyond what the schema already provides for each parameter. The mention of 'base64-encoded image data' and 'Admin-only' provides context but not parameter-specific details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource ('Upload an image to a help article'), but does not differentiate from the sibling tool 'haops_upload_doc_image', which could cause confusion for an AI agent selecting between them.
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 mentions 'Admin-only' as a prerequisite and specifies that it accepts base64 data, but does not provide guidance on when to use this tool versus alternatives like 'haops_upload_doc_image' or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only says 'Update multiple issues at once' without detailing error handling, atomicity, limits, or side effects. This is minimal transparency 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 two sentences, direct and to the point. It provides the essential information without any unnecessary words. Every sentence 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?
Given 4 parameters and no output schema or annotations, the description covers the core purpose and gives examples but lacks details on response format, error handling, or constraints. It is adequate for a simple tool but has gaps for a bulk operation.
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 coverage is 100%, so baseline is 3. The description adds value by linking the 'updates' object fields ('status', 'priority', 'assignedTo') to the mentioned use cases, reinforcing the schema. It does not fully compensate for any gaps but provides good contextual mapping.
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: 'Update multiple issues at once.' It specifies the resource (issues) and the batch nature, distinguishing it from single-issue updates like haops_update_issue. The examples of status changes, priority updates, or reassignments further clarify the use case.
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 context by listing typical use cases ('batch status changes, priority updates, or reassignments'), helping the agent decide when this tool is appropriate. However, it does not explicitly exclude alternatives or state when not to use it, which is a minor gap given the presence of haops_update_issue for single updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds some behavioral context by noting that issues are leaf nodes and no confirmation is needed. It does not disclose other important behaviors like whether the operation is reversible, required permissions, or potential 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 extremely concise: one sentence with a parenthetical addition. It front-loads the action and resource, and every word contributes value. There is no redundancy or filler.
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 3 parameters and no output schema, the description covers the core purpose but does not explain return values, error handling, or the role of the verbose parameter. It is adequate for a simple deletion but lacks depth.
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 all three parameters with 100% coverage. The description does not provide additional semantic meaning beyond what the schema offers, so the baseline score 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 action (delete), the target (issue), and the context (from a HAOps feature). It distinguishes this tool from siblings that delete other entities like features or modules, making the purpose unambiguous.
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 critical usage hint: 'No confirmation needed (issues are leaf nodes with no children),' indicating safe deletion without cascading effects. However, it does not explicitly mention when NOT to use this tool or suggest alternative tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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 only the author can edit, which is a critical behavioral trait, but omits side effects, error handling, or response format details.
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 with two sentences and no extraneous information, efficiently conveying purpose and a key constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (6 params, no output schema), the description covers the core purpose and a constraint but lacks details on response, errors, or behavior beyond author restriction.
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 the description adds no new parameter information beyond what the schema provides. The description does not explain parameter usage beyond the generic purpose.
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 'Edit an existing message in a discussion thread' with a specific verb and resource. It distinguishes from siblings like haops_post_message (create) and haops_delete_message (delete) by specifying the edit action.
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 usage context ('Useful for correcting typos or updating information') and a key constraint ('Only the message author can edit'). However, it does not explicitly mention when not to use the tool or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the output (commits ahead/behind, etc.) but does not explicitly state that the tool is read-only or safe. However, the verb 'Compare' and the nature of the tool imply no side effects, so the transparency is adequate but could be improved.
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 purpose, then lists the return items, and ends with a usage recommendation. There is no wasted text.
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 has 4 parameters, no output schema, and moderate complexity. The description lists the main return items but does not mention response format, pagination, or error conditions. However, for a comparative read operation, the description is reasonably 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 the schema already documents all parameters. The description adds minimal value beyond the schema: it mentions 'two branches' which maps to sourceBranch and targetBranch, but does not elaborate on projectSlug or repositoryName beyond what the schema provides. 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 that the tool compares two branches in a HAOps Git repository and returns specific data (commits ahead/behind, changed files, diff content, conflict detection). It uses a specific verb ('Compare') and resource ('branches'), effectively distinguishing it from siblings like haops_git_commit_diff or haops_merge_merge_request.
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 'Use before creating an MR to preview changes,' providing clear context for when to use the tool. While it doesn't list alternatives or explicitly say when not to use it, the guidance is sufficient for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses that deprecated skills are excluded by default and that filtering is available. However, it does not mention pagination, ordering, or any side effects; for a list tool, this is adequate but not detailed.
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 two sentences that front-load the purpose, then provide context on what skills are and filtering. It is efficient, though could mention that all parameters are optional for completeness.
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 6 optional parameters and no output schema, the description covers purpose and filtering. Missing return format (e.g., array of objects) is a minor gap, but overall it is sufficient for a list tool with clear parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter is well-documented in the schema. The description reinforces filtering but does not add new meaning beyond the schema; thus baseline 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 'List agent skills (system-wide + optionally project-scoped)' and defines skills as reusable, role-tagged knowledge units. This distinguishes it from siblings like haops_read_skill (single skill) and haops_create_skill (creation).
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 lists filters (scope, category, role, project, search) and notes deprecated exclusion by default. Context implies this is for finding skills, contrasting with haops_read_skill, but no explicit when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 tool checks branch protection rules, required approvals, allowed roles, and conflicts before merging, and supports two merge strategies. It does not mention error handling or source branch deletion behavior, but the disclosed behaviors are substantial.
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 with zero fluff. The first sentence states the core function and preconditions; the second adds supported merge types. Information density is high and front-loaded.
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?
No output schema exists, yet the description does not hint at return values or success/failure indicators. The 5 parameters are well-documented, but the agent lacks information on what to expect after the merge, which is a gap for actionable use.
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 baseline is 3. The description does not add extra meaning to individual parameters beyond the schema descriptions. The mention of merge strategies provides context but is not parameter-specific.
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 the action (merge) and resource (merge request) with specific verb+resource. It distinguishes the tool from sibling tools like close, reopen, review, get, and list by explicitly stating it performs merging with precondition checks.
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 that the merge request should be approved and that pre-merge checks are performed, providing some usage context. However, it lacks explicit when-to-use vs. when-not-to-use guidance or alternatives (e.g., 'use close_merge_request if you want to cancel without merging').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: checks availability and marks as in-progress. However, since no annotations are provided, the description carries the full burden. It lacks details on authentication requirements, what happens if the module is already claimed, or error conditions. This is adequate but not thorough.
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 with two sentences. The first sentence covers the action and behavior, the second gives usage context. No extraneous words, well front-loaded.
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 3 parameters, no output schema, and good schema coverage, the description is reasonably complete. It covers purpose, behavior, and usage. However, the lack of annotations means some behavioral details (e.g., side effects, permissions) are missing, which could be improved.
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 the baseline is 3. The description adds no additional meaning beyond what the input schema already provides for the three parameters (verbose, moduleId, checkOnly). No parameter-specific explanation is given in the description.
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 ('Claim a module for work'), the resource ('module'), and the specific behaviors ('Checks availability and marks as in-progress'). It effectively distinguishes from sibling tools like haops_claim_feature, haops_claim_issue, and haops_claim_ticket by targeting a module.
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 says 'Use before starting implementation on a module,' providing a clear usage context. It does not mention when not to use or alternatives, but the resource differentiation among siblings makes the guidance sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 explains the two modes but does not disclose behavioral traits like return value, side effects, authentication requirements, or error handling for a creation 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 well-structured, presenting the two modes in a clear, front-loaded manner with no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, two modes, no output schema), the description adequately covers the essential usage patterns. It lacks detail on the return value but is otherwise complete for creating a discussion.
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 parameters. The description adds context about the two usage modes, but beyond that, the parameter documentation is already detailed in the schema, so the description adds minimal additional semantic value.
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 'Create a discussion thread in a HAOps project' and explains two distinct modes (entity-linked and channel-based), which differentiates it from sibling tools like haops_get_discussion or haops_delete_discussion.
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 guidance on when to use each mode and references haops_list_channels for obtaining a channelId. It clarifies that at least one of channelId or discussableType+discussableId is required, but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses auto-detection of conflicts, snapshotting commit SHAs, and return payload contents. Good detail, but could mention side effects or permissions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, first states core purpose, second adds key behaviors and return value. No fluff, efficient, and front-loaded.
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 7 parameters and no output schema, description covers creation, conflict detection, and return info. Could be more precise about conflict handling (e.g., does creation proceed if conflicts exist?) and error conditions. Still fairly complete for a non-trivial 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 clear descriptions for all 7 parameters. Description adds no extra meaning beyond schema, so baseline 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?
Description explicitly states 'Create a merge request' with specific verb and resource. It distinguishes from siblings like close, merge, list by focusing on creation. It also adds unique details like auto-detecting conflicts and returning diff stats, making purpose very clear.
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?
Implies use when creating a new merge request, but does not explicitly guide when to use this vs alternatives (e.g., merging, closing). No exclusions or prerequisites mentioned. Adequate but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses permanent and cascading deletion (all messages). With no annotations, this provides key behavioral traits, though lacks details on permissions or response behavior.
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 concise sentences, front-loaded with main action and followed by important context. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and main side effect. Schema documents parameters. Lacks mention of response, but sufficient for a delete tool with 3 parameters and no output 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 covers 100% of parameters with descriptions; description adds no additional parameter semantics beyond what schema provides.
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?
Clearly states 'Delete a discussion thread' with specific verb and resource. Distinguishes from siblings like haops_delete_message (single message) and haops_delete_channel (channel).
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?
Implies use with caution due to permanence, but does not explicitly state when to use or not use, nor provide alternatives like update or single-message delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists the returned information (diff stats, reviews, conflict status, branch info) but does not explicitly state that the tool is read-only or has no side effects. Given no annotations, this is adequate but could be more 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?
Two concise, front-loaded sentences: the first states functionality, the second provides usage guidance. No extraneous 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?
Given no output schema, the description adequately lists the categories of information returned. It could be more detailed about the structure but is sufficient for an agent to understand the tool's output.
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 descriptions for both parameters. The description does not add additional semantics beyond the schema, but the schema descriptions are sufficient.
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 ('Get merge request detail') and specifies the resource and included components (diff stats, reviews, conflict status, branch info). It distinguishes from siblings like list_merge_requests (which provides an overview) and merge/review actions.
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 advises using this tool 'to review an MR before approving or merging,' providing explicit usage context. It does not mention alternatives or when not to use, but the guidance 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the result includes inbound, outbound, and internal messages, which is valuable behavioral context beyond the basic get operation. However, no annotations are provided, so the description carries the burden.
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?
One sentence, 17 words, no fluff. Core action is front-loaded.
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 retrieval tool with two required parameters and no output schema, the description provides enough context about what is returned. Could mention that it's a read 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 coverage is 100%, and the description does not add information about parameters 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 gets a helpdesk ticket by ID and includes full conversation timeline. It distinguishes from siblings like haops_list_tickets and haops_get_issue.
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?
No explicit guidance on when to use or not use this tool vs alternatives. The context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description provides some transparency (binary handling, multi-repo), but lacks details on error handling, permissions, or return format beyond basic content.
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 three concise sentences with the purpose front-loaded, containing no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-file tool with no output schema or annotations, the description adequately covers core functionality, binary handling, and multi-repo support, though it omits potential error conditions.
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 coverage is 100%, and the description adds value by explaining that repositoryName supports multi-repo projects, surpassing the baseline 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 verb 'Read' and the resource 'file content from a project's Git repository', distinguishing it from sibling tools like haops_git_commit_diff or haops_git_list_files.
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 notes behavior for binary vs text files and multi-repo support, but does not explicitly state when to use this tool over alternatives or list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden of behavioral disclosure. It mentions filters but does not disclose pagination, result ordering, default behavior, or response structure. For a list operation, pagination is often important. The description is adequate for basic use but lacks key 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: the first states the action and filters, the second provides usage context. It is front-loaded, concise, and every sentence adds value. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a list operation with 5 parameters, no output schema, and many sibling tools, the description is nearly complete. It explains filtering and use case. However, it lacks information on pagination or result format, which is a gap for a list tool. Overall, it is adequately 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?
With 100% schema description coverage, the schema already documents all 5 parameters. The description rephrases filtering options but adds no additional meaning beyond what the schema provides (e.g., entityId requires entityType is already in schema). Baseline is 3; description barely adds value.
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 'List discussions in a HAOps project' with specific filters (by entity, channel, status). It includes a usage context: 'Essential for the Entity Discussion Protocol — use this to find the discussion linked to a work item before posting.' This distinguishes it from other discussion-related tools like haops_create_discussion, haops_get_discussion, haops_search_discussion.
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: 'Essential for the Entity Discussion Protocol — use this to find the discussion linked to a work item before posting.' It implies when to use (before posting, with entity filters) but does not explicitly exclude other scenarios or compare to siblings like haops_search_discussion. The sibling list helps, but the description could be more explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only, non-destructive operation by stating it returns data. However, it does not disclose pagination, permissions, or rate limits. For a listing tool, this is mostly transparent but could include more behavioral details.
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 sentence that is front-loaded with the verb and resource. Every word contributes purpose, making it highly concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description adequately conveys what the tool does and what it returns. However, it does not specify filtering or sorting capabilities, which are common in listing tools.
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?
Both parameters are already described in the input schema with clear descriptions. The tool description adds no additional meaning beyond what the schema provides, so 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 action (list), the resource (sections in a documentation artifact), and the output (hierarchy with titles, slugs, order). This readily distinguishes it from sibling tools like create_doc_section or get_doc_section.
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 reading sections but does not explicitly state when to use this tool over alternatives (e.g., haops_get_doc_section for a single section). No when-not-to-use or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It indicates a read-only operation ('List') and describes return fields, but lacks details on pagination behavior (e.g., total count), ordering, error conditions, or potential side effects. 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?
Two concise sentences, front-loading the action and key details, with no unnecessary words. The use case sentence adds value efficiently.
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 core functionality and output, but omits pagination specifics (though page/limit are in schema) and prerequisites (e.g., project must exist). For a list tool with moderate complexity and good schema coverage, it is mostly 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% with well-described parameters. The description adds no further parameter-specific details beyond the schema, merely summarizing the output fields. The value added is marginal.
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 modules with optional filters and specifies the returned fields (module ID, title, status, priority, owner, feature count). It also provides a specific use case ('discover module UUIDs'), distinguishing it clearly from sibling list 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 gives explicit guidance on when to use the tool ('Use this to discover module UUIDs'), but does not mention when not to use it or compare it with alternatives like haops_get_module for single modules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool is read-only on the MCP surface and that system packs are seeded and cannot be deleted. This provides useful behavioral context, though it omits details like authentication requirements or rate limits, which are less critical for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the purpose and includes necessary context. It is concise but could be slightly more structured (e.g., bullet points). Every sentence contributes value.
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?
There is no output schema, but the description does not specify the structure of returned packs (e.g., fields like id, name, category). It explains the concept well but is incomplete for an agent to fully understand the output. Given the tool's simplicity, this is adequate but not excellent.
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 skill packs and their categories but does not add meaning beyond what the schema already provides for each parameter. The schema descriptions are sufficient.
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 explicitly states 'List skill packs' and defines them as 'curated bundles of agent skills (e.g. helpdesk-pack, security-pack, mobile-pack)'. It clearly distinguishes this read operation from sibling tools like create, update, and deprecate skill packs by noting 'Read-only on the MCP surface; mutations go through the web admin'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading skill packs and notes that system packs 'cannot be deleted', but does not explicitly state when to use this tool versus alternatives like haops_create_skill_pack or other list tools. However, the context of listing vs. mutating is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description implies a read-only operation. It does not disclose additional behavioral traits such as performance impact or required permissions, which are not critical for a simple list tool but could be improved.
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 concise sentences, front-loaded with the core purpose, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description is adequately complete, covering what it lists and when to use it. Missing details like pagination or sorting are not critical for this 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%, and the description mentions the update type parameter by listing example values, but it doesn't add significant meaning beyond the schema's own descriptions and enum definitions.
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 available updates for a project, specifying fields (update type, version, status, date) and examples (MCP server versions, protocol changes, test suites, onboarding templates). It distinguishes from sibling list tools by focusing on updates.
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 says 'Use to check for new MCP server versions, protocol changes, test suites, or onboarding templates', providing clear usage context. However, it does not mention when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals that markdown will be converted to HTML server-side, adding a behavioral detail. However, it omits authentication requirements, rate limits, error handling, or success/failure behavior.
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 with no wasted words. First sentence states the purpose, second gives a practical recommendation. It is front-loaded with 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 tool with 6 parameters, 3 required, and no output schema, the description covers the key markdown conversion aspect but doesn't detail the parentMessageId (threaded replies) or verbose parameter explicitly. The schema provides full coverage, so the description is largely 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?
Schema description coverage is 100%, baseline 3. The description adds value beyond the schema by explicitly recommending markdown for agent messages and noting server-side conversion, which enhances understanding of the content and contentType parameters. It also mentions @mentions, which is present in the schema but reinforces the semantic.
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 posts a message to a discussion thread in HAOps, with a specific verb ("Post") and resource ("message to a discussion thread"). It distinguishes from sibling tools like haops_send_dm (direct message) and haops_create_discussion (creating threads).
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 recommends using markdown for agent messages and notes server-side conversion, providing some usage context. However, it lacks explicit when-not-to-use guidance or comparison to alternatives like haops_edit_message or haops_delete_message.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states 'Read-only — does not mutate', which is a key behavioral trait. However, it does not disclose auth requirements, rate limits, or other potential side effects, which would improve 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 two sentences, front-loaded with the primary action, and no unnecessary words. It efficiently conveys purpose, safety, and usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description covers purpose and usage well. However, it lacks detail on the output format (e.g., what kind of list is returned), which would be helpful for a preview 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%, so the schema already documents both parameters. The description mentions 'named role template' hinting at the 'name' parameter but adds no significant semantic detail 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 purpose: preview which project protocols need rewiring if a role template is bumped via PUT. It specifies the verb 'Preview' and the resource 'project protocols', distinguishing it from sibling tools like haops_update_role_template and haops_preview_skill_cascade.
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 advises to use this tool 'BEFORE calling haops_update_role_template({ ..., cascade: true })' to estimate blast radius, providing clear when-to-use guidance. It implies it's for high-impact templates but does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses that it's a read operation (non-destructive), returns specific fields with hydrated defaultSkills, and mentions raw parameter effect. But lacks depth on error handling, authentication, performance, or caching behavior.
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, each purposeful. First states purpose and return value, second gives usage guideline. No filler, well front-loaded.
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 two parameters and no output schema, description is fairly complete: covers return fields, identifier format, and workflow order. Could note error cases or relationship to update/history tools, but sufficient for basic usage.
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 baseline is 3. Description adds context about hydrated vs structured JSON output for defaultSkills, which complements schema. However, raw parameter is only briefly mentioned and doesn't add significant new meaning.
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?
Description clearly states verb 'Read' and resource 'role template' with identifier 'kebab-case name'. It distinguishes from sibling tool haops_list_role_templates by specifying usage order and that it fetches full contents.
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?
Explicitly states 'Use after haops_list_role_templates to fetch the full template contents', providing clear workflow context. However, it does not mention alternatives like haops_get_role_template_history or haops_update_role_template, nor when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description explains the two modes and their effects. It does not disclose potential side effects (e.g., whether replies are appended to ticket history, rate limits, or authentication requirements). 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?
Extremely concise: a single sentence split into two clauses. Front-loaded with the main action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fairly complete for a reply tool. Explains the two modes and uses. Lacks description of return value or side effects (e.g., how the reply relates to the ticket). The verbose parameter hints at response formats but not fully detailed.
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% (all parameters described). The description adds the semantic distinction between direction values, which is already covered in the enum description. No additional meaning beyond what the schema provides.
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: sending a reply or internal note on a helpdesk ticket. It specifies two distinct modes (outbound and internal) and distinguishes from siblings like haops_create_ticket or haops_close_ticket.
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 explains when to use each direction option (outbound sends email, internal creates private team note). However, it does not explicitly contrast with alternative tools or provide guidance on when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'List all channels,' which implies read-only behavior but does not explicitly confirm no side effects or disclose other behavioral traits. Adequate for a simple list 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?
Two concise sentences with no wasted words. The purpose and usage guidance are front-loaded, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description sufficiently covers purpose, usage context, and linkage to a related tool, making it complete for an agent to select and invoke 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% for the single parameter projectSlug, and the description adds no additional meaning beyond the schema's 'The project slug (URL identifier).' Baseline 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 'List all channels in a HAOps project' with a specific verb and resource, and distinguishes from sibling tools like haops_create_channel, haops_delete_channel, and haops_update_channel.
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 explicit context for use: 'discover channel UUIDs needed for creating channel-based discussions via haops_create_discussion.' However, it does not mention when not to use it or alternatives beyond the linked tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It discloses that the tool returns paginated results and includes an unread count, which is useful behavioral context for a read operation. However, it does not explicitly state that it is read-only or mention any 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 extremely concise: two sentences that front-load the purpose and follow with return info. Every word adds value, and there is no redundancy or unnecessary detail.
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 list tool with low complexity and full schema coverage, the description is complete. It covers purpose, pagination, and unread count, which is sufficient without an output 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%, with both parameters ('page', 'limit') clearly described in the schema. The description adds no additional meaning beyond the schema, so a 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 action ('list'), the resource ('notifications'), and specifies it's for the authenticated user/agent. It also adds that results are paginated and include an unread count, distinguishing it from mutation tools like 'haops_mark_notification_read'.
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 use for viewing notifications but does not explicitly state when to use it versus alternatives like 'haops_mark_notification_read' or provide any exclusions. No guidance on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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 behavioral disclosure. It identifies the tool as a retrieval operation (read-only), but does not explicitly state it is non-destructive, idempotent, or mention any side effects, rate limits, or authentication requirements. The description is adequate but lacks richness.
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 plus an example. Every word adds value, no redundancy. The key information is front-loaded (hybrid retrieval, top-K chunks, entity citations), making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description is brief. It describes the output as 'chunks with entity citations' but does not detail the format, pagination, or behavior when no results are found. While the example provides concrete usage, the description lacks sufficient detail for a fully complete understanding of the tool's output.
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 100%, with each parameter well-described. The description adds an example that demonstrates parameter usage (projectSlug, text, topK) and implies the hybrid mode default. This provides additional semantic context beyond the schema, earning a score above the baseline 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 performs hybrid BM25+vector retrieval over a HAOps corpus, returning top-K chunks with entity citations. The example reinforces its purpose. Among siblings, it is the only RAG query tool, distinguishing it from CRUD and other search tools like search_discussion and search_help.
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 includes an example demonstrating typical usage, which implies context. However, it does not explicitly provide when to use this tool versus alternative search tools (e.g., search_discussion or search_help) or mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 that the tool returns different data structures based on mode, and that full=true includes historical log entries. However, it does not mention permissions, rate limits, or potential side effects. For a read-only operation, this is adequate but could be more explicit about safety.
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 front-loaded with the core purpose and structured logically by mode. While it is somewhat lengthy, every sentence adds value, covering edge cases and configuration. Minor redundancy (e.g., repeating default mode) could be trimmed, but overall it is efficient.
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?
With no output schema, the description adequately explains return values for both modes, including the structure of the lazy envelope. It covers all 5 parameters and their interactions. Missing detail on exact data types or response size, but sufficient for an agent to understand what to expect.
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 100%, so baseline is 3. The description adds significant meaning beyond the schema by explaining how mode and full interact, the structure of lazy output, and the fallback behavior for non-project entities. This justifies a score above baseline.
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 agent memory for a project, module, or feature, and distinguishes two modes (eager and lazy) with specific behaviors. The verb 'read' and resource 'memory' are precise, and the description differentiates from siblings by referencing how it relates to haops_get_doc_section and haops_rag_query.
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 explains when to use each mode: eager for full context, lazy for boot context reduction. It also references sibling tools for on-demand fetching. However, it does not provide explicit when-not-to-use scenarios or compare directly to alternatives like haops_rag_query for context retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: checking availability and marking as in-progress. Without annotations, it adequately covers the core behavioral traits, though it could mention side effects like preventing others from claiming.
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 with no wasted words. The first sentence front-loads the purpose, and the second adds context. Each 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?
The description covers the main action and context. However, it does not explain the return format or error conditions, which would be helpful given no output 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 coverage is 100%, so the schema already describes all parameters well. The description adds no additional parameter information beyond what is 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 action ('claim'), the resource ('feature'), and the effect ('marks as in-progress'). It distinguishes from sibling claim tools for other entities (issues, modules, tickets) by specifying 'feature'.
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 before starting implementation on a feature'), but does not explicitly mention when not to use 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool checks availability and marks as in-progress, which covers the core behavioral traits. It does not mention permissions or side effects, but is adequate for a claim 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?
Two sentences with no wasted words. Front-loaded with the primary action, then behavioral details and usage hint. Efficiently 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?
Given the tool's low complexity (3 parameters, no output schema, no nested objects), the description covers the essential aspects: purpose, behavioral flow, and usage timing. Could mention return format but not critical.
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 each parameter well-described. The description does not add new parameter-level meaning beyond what the schema provides, so baseline 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 verb 'Claim' and the resource 'issue for work', and further explains it checks availability and marks as in-progress. This distinguishes it from sibling claim tools for different entities (feature, module, ticket).
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 gives a clear usage context: 'Use before starting implementation.' However, it does not explicitly differentiate from other claim tools like haops_claim_feature or provide when-not-to-use guidance, but the resource specificity ('issue') helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It discloses soft-delete vs. hard-delete, cascading across all versions, toggling isDeprecated=true, preservation of history via a separate endpoint, admin-only restriction, feature flag dependency, and the return structure ({message, versionCount}).
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 sentences with no redundant words. Key information is front-loaded (soft-delete and deprecate), followed by cascading behavior, history visibility, access control, and return type. Every sentence adds distinct value.
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 main behavioral aspects (cascade, soft-delete, history, admin, return). Lacks error scenarios or rate limits, but the complexity is well addressed. Return structure is specified despite no output 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 coverage is 100% (all parameters documented), so baseline is 3. The description adds value by explaining cascade behavior and specifying name as kebab-case, but does not elaborate on scope, verbose, or projectSlug beyond schema comments.
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 explicitly states 'soft-delete + deprecate a skill', specifies the API endpoint, and details cascading behavior across all versions with a return value. It clearly distinguishes from sibling deprecate tools like haops_deprecate_role_template and haops_deprecate_skill_pack.
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 identifies admin-only access and a feature flag gate, but does not explicitly compare with alternatives such as haops_transition_skill or haops_delete_skill. Usage context (when to deprecate vs. delete or update) is implied but not systematically stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly describes the tool as a read operation returning health data with a server configuration requirement. Does not mention pagination or performance implications, but for a diagnostic read, the description is transparent enough.
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 plus a requirement line, no fluff. Front-loaded with the core purpose, efficient 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?
With no output schema, the description gives a good sense of return data (missing UUIDs, deprecated refs, etc.) and connects to the UI. Could mention snapshot metadata format, but sufficient for a simple diagnostic 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%, so the description does not need to add extra parameter details. It does not elaborate on parameters beyond the schema, which is acceptable given high coverage. Baseline 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?
Description clearly states it returns per-role composed-protocol health, listing specific data types (missing skill UUIDs, deprecated references, etc.) and references the UI panel, distinguishing it from sibling tools like haops_read_protocol or haops_get_protocol_spawn_lines.
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?
Mentions the required server flag (ENABLE_COMPOSED_PROTOCOLS=true) and states it surfaces the same data as the UI panel, providing clear context. Does not explicitly list when not to use or compare to alternatives like haops_work_entity_health_check, but sufficient for a read-only diagnostic tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully discloses the read-only nature, the required feature flag, and the 404 behavior. This is transparent and covers key 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 short paragraphs, front-loaded with the core purpose, and every sentence adds value (definition, usage, conditions, error handling). 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?
Given the simplicity (3 params, no output schema) and lack of annotations, the description is complete: it covers purpose, parameters, prerequisites, and error cases. It could briefly mention the return format, but the description implies it returns spawn-line text.
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 baseline is 3. The description adds context for the 'role' parameter (omit for all, specify for one) and explains the 'raw' parameter, but the schema already describes these. No additional semantics beyond what is 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 returns per-role spawn-line text and defines spawn lines. It specifies the API endpoint and distinguishes the resource (spawn lines) from sibling tools that handle other entities.
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 explains when to use the tool (to get spawn lines), how to use parameters (omit or specify role), and mentions the feature flag requirement and 404 handling. It does not explicitly compare to alternatives, but no other spawn-line tool exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It explains the return structure, the diff behavior, and the accessibility of soft-deleted skills. This is transparent and adds value beyond the schema.
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 well-structured sentences: function, use cases, and an administrative note. Front-loaded with the core purpose. No unnecessary 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?
The description covers the return format and diff feature, which compensates for the lack of an output schema. It does not mention pagination or limits, but given the tool's nature, this is acceptable. Overall, it is sufficiently 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 description coverage is 100%, and the schema already explains all parameters, including the conditional dependency between scope and projectSlug. The description reinforces but does not add significant new 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 clearly states that the tool returns the full version history of a named skill, specifying the endpoint and what each entry contains. It distinguishes itself from sibling tools by focusing on history, not current state or listing.
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 (audit content changes, recover from bad publish, inspect lineage) and an administrative note about soft-deleted skills. It does not explicitly state when not to use, but the guidance is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 it returns SSH URL, default branch, and setup commands, and supports multi-repo. It does not mention side effects or permissions, but for a read-only tool that's acceptable.
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 concise sentences: main purpose, return values, multi-repo note. No wasted words, front-loaded, and efficiently 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?
Given no output schema and no annotations, the description covers the main purpose, returns, and parameter usage. It is adequate for a simple get tool, though it omits potential error conditions.
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 baseline is 3. The description adds minimal value: it reinforces multi-repo support but does not provide new parameter semantics 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 gets SSH remote URL and setup instructions, distinguishing it from other git tools like haops_git_commit_diff or haops_git_list_files. The verb 'Get' and resource 'SSH remote URL and setup instructions' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing remote URL and setup commands, but does not explicitly exclude alternatives or mention when not to use. It provides clear context but lacks explicit when-not or sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 of behavioral disclosure. It describes the verdicts and auto-transition, but lacks details on idempotency, permissions, whether reviews can be overwritten, or the return format. 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?
The description is two sentences, front-loaded with the main action, and every sentence adds value. No unnecessary words 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?
Given the five parameters, no output schema, and no annotations, the description covers the core purpose, verdict options, and a key behavioral aspect (auto-transition). It lacks information on permissions or error states, but for a review action, it provides sufficient context for an AI agent.
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 coverage is 100%, so each parameter is documented. The description adds meaning by explaining the verdict values and their effect (auto-transition), which provides context beyond the enum listing. However, it does not add specific details to other parameters like body or verbose.
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 'Submit a review on a merge request' with a specific verb and resource. It lists the three verdicts and mentions auto-transition behavior, distinguishing it from sibling tools like merge, close, reopen, and get.
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 explains when the tool is used (submitting a review) and notes that when enough approvals are met, the MR status auto-transitions to approved. It does not explicitly state when not to use it or compare to alternatives, but the context is clear for a review action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that slug must be unique among siblings (409 on collision), that it cannot address a section with empty slug, and that verbose flag alters response. It does not explicitly state that updates are overwrites or mention permissions, but the behavioral traits are largely covered.
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 plus an 'IMPORTANT' note—front-loaded with purpose, then critical usage detail. No wasted words. Every sentence adds 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 tool with 8 parameters, 3 required, and no output schema, the description sufficiently covers how to identify the section (projectSlug, artifactSlug, sectionSlug), what can be updated, and the verbose option. It lacks details about the default compact summary and error handling beyond slug collision, but overall it is adequate for agent invocation.
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 baseline is 3. The main description adds value by emphasizing the artifactSlug kebab-case rule and the slug uniqueness constraint, but these are also present in the schema descriptions. The additional emphasis does not significantly elevate the score beyond baseline.
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?
Description clearly states the verb (update) and resource (documentation section) and lists the fields that can be updated (content, title, slug, source hint). It also immediately distinguishes this tool from other update-* tools by noting the use of artifactSlug (kebab-case) instead of UUID, making its purpose specific and differentiating it from 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?
Description explicitly warns about the identifier exception ('Uses artifactSlug — NOT the artifact UUID. This is an exception: most other update-* tools use UUID identifiers.') and advises using haops_list_doc_artifacts to find the slug. This provides clear context for when to use this tool. However, it does not mention when not to use it (e.g., for updating other entities) or provide explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses two key behavioral traits: the action is permanent and only executable by the message author. This is sufficient for a delete operation, though it does not detail side effects like cascade deletions.
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 with no wasted words. It front-loads the purpose and then adds constraints. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and four well-documented parameters, the description provides enough context: the action, the required permissions, and the permanence. The sibling tools cover other delete operations, so the differentiation is clear.
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 descriptions for all four parameters (100% coverage), so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema provides; it only contextualizes the overall operation.
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 'delete' and the resource 'message from a discussion thread', and distinguishes it from sibling tools like haops_delete_discussion or haops_delete_channel by specifying the context (discussion thread). It also adds constraints (only author, permanent).
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 a prerequisite (only message author can delete) and the permanent nature, giving clear context for when to use. It does not explicitly mention when not to use or alternatives, but the sibling list includes haops_edit_message for editing, and the constraint implicitly guides usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 that the output includes full HTML content but does not mention whether the operation is read‑only (implied) or any potential side effects, rate limits, or other behavioral traits. The transparency is adequate but minimal.
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 purpose and output, followed by a usage guideline. Every sentence earns its place with no wasted words.
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 simplicity of the tool (one required parameter, no output schema, no nested objects), the description is complete: it states the input, output, and usage context. 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 schema coverage is 100% with one parameter (slug) described as 'The article slug to fetch'. The description adds 'by slug', which repeats the schema. No additional semantics are provided beyond the schema, so a 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 gets a help article by slug and includes full HTML content. It uses a specific verb and resource, and distinguishes itself from sibling tools by referencing haops_update_help_article.
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 explicitly advises using this tool before haops_update_help_article when appending to existing content, since the update tool does wholesale replacement. This provides clear when‑to‑use guidance and an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that both published and unpublished sections are returned, which adds behavioral context beyond the empty schema. Since no annotations are provided, this transparency is valuable, though it omits details like pagination or authentication.
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 action, and contains no unnecessary words. It efficiently conveys the tool's purpose and output.
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 has no parameters and no output schema, the description provides sufficient information: what is listed (help center sections) and what is included (article counts and status). It is complete for its simplicity.
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 no parameters, and schema coverage is 100% (empty). The baseline for zero parameters is 4, and the description does not need to add parameter info.
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 help center sections with article counts, specifying the verb (list), resource (help center sections), and additional detail (article counts). It distinguishes itself from siblings like haops_list_help_articles by focusing on sections.
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 states what the tool does but does not provide explicit guidance on when to use it vs alternatives, such as haops_list_help_articles. Usage is implied but not directly addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the key behavioral nuance of using slug instead of UUID. However, it does not mention error handling, permissions, or whether the operation is reversible. This is a moderate gap for a creation 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 concise, front-loads the purpose, and includes a critical note in 2 sentences. Every sentence is purposeful.
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 no output schema or annotations, the description covers the core function and key identifier nuance. It lacks details on return format or error conditions, but the verbose parameter hint provides some context. Mostly complete for a creation 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%, baseline 3. The description adds value for artifactSlug by explaining its format and usage, but other parameters (title, content, etc.) are already well-documented in the schema. No significant additional meaning beyond 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 'Create a new section within a documentation artifact,' specifying the verb 'create' and the resource 'doc section'. It distinguishes from siblings like haops_create_doc_artifact by noting the unique identifier type.
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 that artifactSlug uses kebab-case slug, not UUID, and directs users to haops_list_doc_artifacts for resolution. This provides clear when-to-use and alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the effects: system-wide scope, versioning defaults (version=1, isCurrent=true, isSystem=false), and the nature of baseBody as admin-trusted markdown with no sanitization. It also explains defaultSkills behavior. However, it omits potential error responses or reversibility.
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 three sentences, with the primary action first. Every sentence provides essential information without redundancy. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (3 required) and no output schema, the description covers creation behavior, defaults, and important constraints. It explains the return value ('Returns the created template row') and key behavioral notes. It could be more complete with error handling or rate limits, but it is largely 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?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that baseBody is admin-trusted and defaultSkills defines auto-enabled skills with the 'required' flag meaning non-disable-able. It also clarifies name uniqueness and character constraints 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 it creates a new agent role template, specifying admin-only and feature flag requirements. It distinguishes itself from sibling tools like haops_update_role_template and haops_deprecate_role_template by explicitly labeling the action as 'create' and detailing unique behaviors like version=1, isCurrent=true.
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 on when to use the tool: admin-only access and the composed-protocols feature flag requirement. It does not explicitly state when not to use it or compare with alternatives, but the constraints (admin, feature flag) are well-communicated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: soft-delete vs hard delete, cascading across versions, admin-only requirement, feature flag dependency, and 403 error for system templates. It could elaborate on reversibility or cascading details, but the audit context note adds value.
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 sentences, each packed with essential info: action, constraints, exceptions, and audit behavior. Front-loaded with the core purpose. 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 tool with 2 parameters, no output schema, and no annotations, the description covers prerequisites, side effects, and edge cases. It could mention the response format, but the verbose parameter implies a structured response. Overall, sufficient for invocation.
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 clear parameter descriptions. The description does not add extra meaning beyond the schema, so baseline 3 applies. The description does not repeat parameter info, but the schema already suffices.
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 ('soft-delete'), the resource ('role template'), and distinguishing features: cascading across all versions, admin-only, requires composed-protocols feature flag. It also contrasts with system templates, setting it apart from sibling tools like haops_deprecate_skill and haops_delete_* tools.
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 to use (soft-delete of non-system templates with feature flag) and when not to use (system templates return 403), providing alternatives: 'publish a new version via haops_update_role_template or alter the seeder.' Also mentions that soft-deleted rows remain visible in history for audit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that covers fails silently, returns thin rows (not full bodies), and lists returned fields. This is adequate behavioral disclosure for a read tool.
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?
Well-structured with sections for primary usage, secondary usage, returns, and example. Front-loaded with purpose. Could be slightly more concise, but it is well-organized and each part earns its place.
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?
No output schema, but description fully explains return values and how to use them (feed entityId into haops_get_doc_section). Covers main use cases, combination of filters, and example. Complete for a discovery 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 coverage is 100%, but description adds significant meaning: controlled vocab for relevantTo (roles and task-types listed), dual-filter strategy, and warning about covers brittleness. This goes 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 a specific verb+resource: 'discover' which doc sections cover a topic before reading full bodies. It distinguishes itself from sibling tools like haops_get_doc_section (retrieves full body) and haops_rag_query (likely retrieves content) by emphasizing it returns thin metadata rows.
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 guidance: use before reading full bodies, filter by scope (relevantTo) then pinpoint (q). Secondary usage with covers is warned as brittle. Includes an example. While not explicitly listing when not to use, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that role templates are system-wide (no scope/projectSlug), what each history entry contains, and the effect of diff=true. It does not mention pagination or limits, but for a history tool this is acceptable.
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 well-structured paragraphs. First explains what the tool does, second provides use cases. No fluff, every sentence adds value.
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?
No output schema, but description lists the fields included in each entry. For a read-only query tool, this is sufficient. It might benefit from mentioning any pagination or limits, but not critical.
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?
Input schema has 100% description coverage. The description adds meaningful context: diff controls unified diffs between consecutive versions, raw controls raw JSON vs formatted table. Name is just 'kebab-case role template name', which is adequate.
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 it returns the full version history of a named role template, with specific fields like version, timestamp, author, lifecycle state, and baseBody markdown. It distinguishes itself from siblings like haops_read_role_template and haops_list_role_templates by focusing on history.
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: audit template content, recover from bad publish, inspect changes before bumping with cascade. It also explains when to use diff. However, it doesn't explicitly state when not to use this tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only — does not mutate,' which is the key behavioral trait. Since no annotations are provided, the description carries full burden and adequately addresses the tool's safety profile. However, it could be more transparent about the nature of the output (e.g., a list of affected consumers) or potential edge cases.
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-loading the core purpose and critical usage guidance. Every sentence adds value: the first states what it does and its read-only nature, the second provides a concrete use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations or output schema, the description covers the essential context: purpose, safety (read-only), and usage sequence. It does not describe return format or prerequisites beyond the input parameters, but the complexity is moderate and the description is sufficient for an agent to infer likely behavior.
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 baseline is 3. The description adds minimal parameter semantics beyond what the schema already provides. It mentions 'named skill' which maps to the 'name' parameter, but does not elaborate on 'scope', 'projectSlug', or 'raw'. Agent must rely on schema descriptions, which are clear but could be reinforced in the description.
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: 'Preview which consumers (role templates, skill packs, project protocols) would need re-wiring if the named skill is bumped via PUT.' It uses a specific verb 'Preview' and identifies the resource and scope. This distinguishes it from siblings like haops_update_skill and haops_preview_role_template_cascade.
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 provides explicit usage guidance: 'Use BEFORE calling haops_update_skill({ ..., cascade: true }) on a high-impact skill to estimate blast radius.' This tells the agent exactly when and in what sequence to use this tool. It also clarifies it is read-only, further guiding appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. Discloses endpoint, error responses (409, 403), condition for system templates, and param naming quirk. Could mention idempotency or side effects, but sufficient.
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?
Front-loaded with purpose, then details. Warning about param naming is important but slightly redundant with schema description. Overall 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?
No output schema, but description covers lifecycle, constraints, errors, permissions, and verbose flag. For a 3-param tool, it is very 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?
Schema covers all parameters (100%). Description adds value by warning that param is named 'action' not 'status', and explains allowed values and verbose parameter effect.
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?
Explicitly states the verb 'transition' and resource 'role template' with specific lifecycle actions (propose/publish/deprecate). Distinguishes from sibling tools like haops_transition_skill and haops_transition_skill_pack by naming the resource.
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?
Describes prerequisites: admin-only, requires ENABLE_COMPOSED_PROTOCOLS=true. Mentions server-enforced state machine and error codes. Does not explicitly compare to alternative tools like haops_update_role_template.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses role restrictions ('Admin and architect roles ONLY') and the replace-mark action. It implies replacement of old baseText, which is a destructive behavior, but does not elaborate on reversibility or 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 two sentences with a clear action and purpose, plus a role restriction. It is front-loaded and every sentence adds value.
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 explains the tool's purpose, parameters, and usage context. However, it lacks details about return value or error behavior, which would be helpful since there is no output schema.
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 100% and the description adds value by clarifying that newBaseText should incorporate pending log entries and that integrateUpTo defaults to all pending when omitted. This goes beyond schema 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 clearly states the tool does 'consolidate entity agent memory' by replacing baseText and marking log entries as integrated. It differentiates from siblings like haops_append_memory by focusing on consolidation rather than appending.
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 guidance to 'Use this to keep baseText concise by integrating accumulated log entries.' However, it does not mention when to avoid this tool or discuss alternatives like haops_append_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: admin-only requirement, feature flag dependence, conflict handling (409), error when flag off (404), and response structure (id, scope=project, projectId, version=1). Lacks mention of any destructive side effects, but as a create 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?
Concise yet complete: single paragraph with clear progression from purpose to scope to alternatives to requirements to errors to response. Every sentence adds unique value.
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 8 parameters, 6 required, no output schema, and no annotations, the description covers purpose, scope, alternatives, prerequisites, error codes, and response fields. Leaves no critical question unanswered.
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 baseline is 3. The description does not add extra meaning to parameters beyond the schema's own descriptions. No additional parameter clarifications provided.
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 creates a project-scoped skill, specifies the API endpoint, explains the scope visibility, and distinguishes it from the system-scoped sibling haops_create_skill.
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 provides when-to-use (project-scoped), when-not-to-use (use haops_create_skill for system-wide), and alternative tool name. Also outlines prerequisites (admin-only, feature flag) and error scenarios with suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It discloses that the operation returns the full Markdown content as a string (not a file download), which is the key behavioral trait. It doesn't mention side effects, auth, or rate limits, but for an export operation, these are not critical and the description is 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 only two sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words, 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?
Given the tool's simplicity (two required params, no nested objects, no output schema), the description fully explains what it does, what it returns, and a typical use case. It is complete for its complexity level.
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 coverage is 100% with both parameters described. The description adds context by providing example values for artifactSlug ('architecture', 'developer', 'api') and ties the tool to git syncing, which adds meaning beyond the schema's brief 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 clearly states 'Export a documentation artifact as Markdown text' with specific verb 'Export' and resource 'documentation artifact'. It distinguishes from siblings like create/update by emphasizing it returns content as a string, not a file. The use case 'syncing documentation to a git repository' adds 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?
The description mentions 'Useful for syncing documentation to a git repository', providing a clear context for when to use this tool. It doesn't explicitly state when not to use or list alternatives, but among siblings, no other export tool exists, so usage is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the return content (full markdown + metadata) and the effect of the 'raw' parameter. Though no annotations, the description sufficiently conveys this is a read 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?
Two sentences: first states action and output, second gives usage context. No superfluous content. Efficient and well-structured.
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?
No output schema, but description details return values: markdown content and metadata fields. Also covers the 'raw' mode. Sufficient for an agent to understand the tool's output.
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 coverage is 100% and description adds meaning: explains kebab-case requirement, version pinning use, projectSlug necessity when scope='project', and the raw parameter's effect. Exceeds baseline.
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 (read a single skill by kebab-case name) and the resource (skill). It differentiates from siblings haops_list_skills and haops_read_protocol, making it easy for an agent to select.
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?
Explicitly advises using after haops_list_skills or haops_read_protocol('lazy') to fetch instructions on demand. Provides clear context but does not explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full transparency burden. It discloses that insertion sets version=1 and isCurrent=true, that it is admin-only and feature-gated, and that it returns the new skill row or 409 on conflict. This is good, but lacks details on whether the operation is idempotent (it is not, as 409 indicates), and doesn't specify if the returned 'skill row' contains all fields. Still, it provides essential behavioral context for safe invocation.
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 four sentences, each serving a distinct purpose: main action, versioning detail, access/feature gate, and return/conflict behavior. It is front-loaded with the core purpose and avoids unnecessary elaboration. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters (6 required), enums, no output schema, and no annotations, the description covers the key points: scope handling, versioning, conflict resolution, access controls, and return type. It could mention the exact structure of the returned row or whether the skill is immediately active, but it provides sufficient completeness for an agent to decide and invoke correctly.
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 coverage is 100% with each parameter described. The description adds value beyond schema by clarifying the 'scope'-'projectSlug' dependency (scope=system omits projectSlug, scope=project requires it), the versioning semantics (version=1, isCurrent=true), and the conflict behavior. This extra context helps the AI understand parameter relationships beyond individual 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?
Description starts with 'Create a new agent skill (system or project-scoped)', which clearly states the verb and resource. It also explicitly distinguishes from sibling tools like haops_update_skill by noting conflict resolution, and from haops_bulk_publish_skills by implying this is for single skill creation. The purpose is unmistakable and unique among siblings.
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 explicitly states 'Admin-only on the server, gated by ENABLE_COMPOSED_PROTOCOLS', indicating prerequisite context. It also provides explicit when-not guidance: '409 if a skill with the same name already exists... use haops_update_skill to publish a new version instead'. This gives clear direction on when to use this tool vs an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. Discloses preconditions (admin, flag), error behavior (404), field constraints (real UUIDs, not names), default values (isFeatured false, skillIds empty), and return type (created entity). Covers all important 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph of 4-5 sentences, front-loaded with key constraints. Concise given the complexity of 6 parameters and multiple constraints. Could be more scannable with bullet points but remains efficient without fluff.
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?
Thoroughly covers prerequisites, error behavior, parameter constraints, default values, field relationships, and return value. No output schema exists, but return is described. Complete for correct invocation with no 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?
Schema coverage is 100% (all params have descriptions). Description adds value by clarifying that skillIds are UUIDs NOT names, provides example kebab-case name, and links to API endpoint. Offers context beyond schema, like field relationships and defaults.
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 function: 'Create a new skill pack' with specific verb and resource. It distinguishes from siblings by noting that system packs are seeded, not created via API, and lists constraints like admin only and feature flag requirement.
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?
Explicitly specifies prerequisites: 'admin only, requires ENABLE_COMPOSED_PROTOCOLS=true on the server' and behavior when flag is off ('returns 404'). Contrasts with system packs seeding, providing context but no explicit exclusion for other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully covers behavioral aspects: server-enforced state machine, error response details (409 with allowed transitions), admin-only requirement, and the warning about parameter naming. It also notes side effects of transitions.
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 yet informative, with key points front-loaded: purpose, actions, and critical warnings. Every sentence adds value without 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?
No output schema, but the tool is straightforward. The description covers error handling, state machine, and configuration requirements. Slightly less complete due to missing return value details, but still adequate.
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 coverage is 100%, so baseline is 3. The description adds meaning: explains action enum values, scope and projectSlug relationship, verbose behavior, and warns about parameter naming. This enriches understanding 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 explicitly states the action: 'Transition a skill through its lifecycle (propose / publish / deprecate).' It uses the verb 'transition' and mentions the resource 'skill lifecycle'. It distinguishes itself from siblings like haops_deprecate_skill and haops_create_skill by focusing on the lifecycle actions.
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: 'Admin-only, requires ENABLE_COMPOSED_PROTOCOLS=true' and mentions project-scope handling. It warns about the parameter naming conflict. However, it does not explicitly state when not to use this tool versus alternatives like haops_deprecate_skill.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses HTTP method and endpoint, unversioned nature, server-enforced state machine with 409 errors, 403 for system packs, and required config flag. This is comprehensive.
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 and front-loaded with the core purpose, but it is slightly long. All sentences contribute value, though some could be streamlined.
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 no output schema, the description covers key aspects: action, errors, constraints, and parameter details. It does not describe the full state machine or return structure beyond verbose flag, but it is sufficient for an admin tool with clear error handling.
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 coverage is 100%, but the description adds significant value by explaining the lifecycle state machine, warning about the parameter naming (action vs status), and clarifying the effect of verbose. It enriches the schema meaning.
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 transitions a skill pack through its lifecycle (propose/publish/deprecate), specifying the verb and resource. It distinguishes from sibling tools like haops_update_skill_pack by noting that system packs cannot be deprecated and should use update instead.
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 context: admin-only, requires ENABLE_COMPOSED_PROTOCOLS=true, and when not to use (system packs for deprecation). However, it does not address the overlap with sibling tool haops_deprecate_skill_pack, which may cause confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It discloses that each update creates a new version and marks the previous as historical, explains partial update semantics (server carries forward unchanged fields), and conditional F3 fields. However, it lacks details on rate limits, exact response structure, or what happens on error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, front-loading the main purpose. It is somewhat verbose but every sentence adds value. Minor improvement could be trimming redundant phrasing, but overall it is efficient.
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 complexity (7 parameters, nested skillsConfig object, F3 feature flags) and no output schema, the description is quite complete. It covers update mechanism, partial updates, role restrictions, and conditional fields. It does not fully specify the return value or error conditions, but the verbose parameter hints at a response structure.
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 coverage is 100%, and the description adds significant meaning beyond the schema. It explains partial-body update behavior, common usage patterns, and conditional behavior for F3 fields (e.g., templateId carries forward when omitted, skillsConfig can be cleared with null). This provides actionable guidance for parameter usage.
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 updates the work protocol for a specific agent role, creating a new version. It uses a specific verb ('Update (create new version of)') and resource ('work protocol'), and distinguishes from siblings like haops_read_protocol and haops_preview_project_protocol by focusing on updates.
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 provides explicit usage guidelines: partial-body support, common usage patterns (e.g., rebinding templateId, enabling/disabling skills), and role restrictions (Architect and admin only). It also explains when to pass 'content' versus other fields, giving clear when-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: transactional versioning (flip isCurrent, insert at version+1), partial updates, no-op returns unchanged row, immutability of name and isSystem. No annotations exist, so description carries full burden and does so comprehensively.
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?
Four concise sentences front-load purpose and constraints. Every sentence adds unique value without redundancy. Efficient and scannable.
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?
Covers all major behaviors: admin requirement, feature flag, transactional versioning, partial updates, no-op, immutability. Missing mention of return format (compact vs verbose via the verbose parameter) is a minor gap given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all 7 parameters with 100% coverage. The description adds value by explaining partial update semantics ('only supply fields you want to change') and immutability, which aids correct usage beyond schema 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 explicitly states it publishes a new version of an existing role template, clearly distinguishing from create, deprecate, and transition tools. It specifies admin-only and feature flag requirements, leaving no ambiguity about the tool's core function.
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 good guidance: admin-only, feature flag, partial update semantics, no-op behavior. Includes immutable fields. However, it could explicitly state when to use alternatives like create_role_template or transition_role_template, though sibling context helps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral transparency. It discloses the atomic transaction behavior, the no-op handling (mirroring PATCH semantics), the requirement for at least one mutable field, admin-only access control, and the feature gate (ENABLE_COMPOSED_PROTOCOLS). No contradictions exist.
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 compact three sentences. The first sentence states the core purpose and API endpoint. The second covers version bump and no-op behavior. The third specifies mandatory fields and access constraints. It is well-organized, front-loaded, and every sentence adds essential information 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?
Given the tool's complexity (10 parameters, admin-only, version bump logic, cascade behavior), the description covers key aspects: the endpoint, atomicity, no-op handling, field requirement, return behavior (compact vs full response via verbose param), and access control. It does not mention error cases or validation, but the schema and context signals fill some gaps. Overall, it is sufficiently complete for an agent to use correctly.
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 100% description coverage, so the baseline is 3. The description adds value by stating 'At least one mutable field must be supplied,' which is not explicitly in the schema (only name is required). It also enhances the cascade parameter's explanation. This extra context justifies a score above baseline.
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: 'Publish a new version of an existing skill' with the underlying API call. It specifies the action (publish/update), the resource (existing skill), and the effect (server bumps version in a single transaction). This distinguishes it from related tools like haops_create_skill and haops_deprecate_skill.
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 contextual guidance: it explains the no-op behavior (no field difference means no version bump), requires at least one mutable field, and notes that the tool is admin-only and gated by a feature flag. While it doesn't explicitly list alternatives or state when not to use, the purpose and constraints are clear enough for an agent to make appropriate choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral transparency. It discloses the soft-delete nature, the 'paranoid destroy' pattern, lack of cascading, the required admin privilege and feature flag, the specific error for system packs, and the return type ('server confirmation message'). This equips the agent with a comprehensive understanding of the tool's effects and constraints.
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, starting with the core action and then efficiently covering constraints, error conditions, and alternatives. Every sentence serves a purpose, with no redundant or extraneous information. It packs crucial details into a single paragraph.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (auth requirement, feature flag, special handling for system packs, and no output schema), the description is complete. It covers authorization, preconditions, error handling, return value, and provides an explicit workaround for a common failure case. There are no obvious gaps left for the agent to infer.
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 the input schema already describes both parameters (name and verbose). The description does not add any additional semantics beyond what's in the schema; it mentions verbose implicitly via 'If true, return the full API response' but that's already stated. Therefore, the description provides no extra value for parameter understanding, warranting a 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's action: 'Soft-delete (deprecate) a skill pack'. It immediately distinguishes it from other tools by specifying the resource (skill pack) and the nature (soft-delete, unversioned, no cascade), setting it apart from related sibling tools like haops_deprecate_skill or haops_delete_channel.
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 provides explicit usage guidelines: 'Admin only, requires ENABLE_COMPOSED_PROTOCOLS=true', and explains when not to use it: system packs cannot be deleted, with a clear alternative: 'to "deprecate" a system pack, update its skillIds to empty via haops_update_skill_pack instead'. This gives the agent precise context for choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden: clearly states it's non-persisting, describes response shape with preview flag, and documents the feature flag dependency and 404 behavior.
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?
Five sentences efficiently cover purpose, usage, and behavior; front-loaded with key guidance. Slightly verbose but every sentence earns its place.
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?
Despite no output schema, the description specifies the response shape (mirrors haops_read_protocol with preview flag) and covers all essential aspects for correct usage, including error handling.
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 coverage is 100%, baseline 3. Description adds value by explaining parameter defaults (e.g., 'leave unset to use project's current') and links them to the preview context, though the enum for role is already self-explanatory.
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 as a dry-run preview for composing protocol, explicitly distinguishes from haops_update_protocol and haops_read_protocol by contrasting persistence vs non-persistence.
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 advises to use BEFORE haops_update_protocol to verify resolution and warnings, and explains the behavior when no optional params are provided. Also notes the server feature flag requirement and the 404 response when disabled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/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 thoroughly discloses: no version bump, audit log captures diff, admin requirement, feature flag dependency, immutability of name/isSystem, no-op when no changes, full replacement semantics for skillIds, and return of updated entity. No contradictions.
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 a single paragraph but well-structured: starts with core behavior, then constraints, then parameter-specific notes. It is relatively concise given the complexity, though could be slightly more organized with bullet points. Every sentence adds value.
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?
With 6 parameters (1 required) and no output schema, the description covers all necessary aspects: update behavior, immutability, no-op, skillIds replacement, audit log behavior, and return type. It explains when audit rows are written and mentions admin and feature flag. Complete for its complexity level.
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 coverage is 100%, but the description adds significant value beyond schema: explains 'name' as a lookup key, 'verbose' controls response detail, 'skillIds' must be full replacement with constraints (current, non-deprecated, system-scope), and category implies re-categorization. The no-op behavior is a critical addition not in 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 'Update an existing skill pack in place — no version bump', specifying the action (update), resource (skill pack), and key behavioral trait (in-place, unversioned). It distinguishes from creation by noting immutable fields and from other updates by mentioning audit log and no-op behavior.
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 says 'Admin only, requires ENABLE_COMPOSED_PROTOCOLS=true', provides prerequisites. It explains when the tool should be used (update existing pack), what not to do (immutable fields), and describes no-op behavior. It also gives guidance on skillIds as a full replacement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses partial-failure semantics, full transaction rollback on any validation error, admin-only restriction, feature flag requirement (`ENABLE_COMPOSED_PROTOCOLS=true`), and a warning about cascade rewiring. It also mentions checking `totalFailed` in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: main functionality, partial-failure details, admin/feature flag requirements, and a warning. Every sentence provides necessary information without 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?
Despite lacking an output schema, the description includes enough context: success/failure indicators, prerequisites (admin, feature flag), side effects of cascade, and recommended preview step. For a complex bulk atomic operation, this is remarkably 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?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that entries can be partial updates ('Only supply the fields you want to change'), explaining the conditional requirement for `projectSlug`, and default behavior for cascade and verbose. This goes 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 begins with 'Atomically publish multiple skills in a single DB transaction' which is a specific verb+resource. It explicitly distinguishes the tool from the sibling `haops_update_skill` by highlighting batch efficiency ('significantly cheaper than N sequential haops_update_skill calls during mass refactors').
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 explicitly states the use case: 'mass refactors' and recommends running `haops_preview_skill_cascade` on high-impact skills before to estimate blast radius. It implicitly contrasts with individual updates by naming `haops_update_skill` as the alternative for single updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses output shapes for all scenarios (legacy, composed lazy/bundle, versioned historical), including side effects (e.g., mode ignored for legacy). No contradictions.
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?
Well-structured with front-loaded purpose and organized output shapes section. Slightly verbose but necessary due to complexity.
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?
Covers all edge cases (legacy, composed, historical versions) and explains return shapes despite no output schema. Complete for a complex tool.
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 coverage is 100%, and the description adds significant behavioral context beyond schema (e.g., how mode affects output, version overriding mode, role semantics). Baseline 3 exceeded.
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?
Clearly states the tool reads the work protocol for a specific agent role in a project, distinguishing it from siblings like haops_read_role_template and haops_read_skill.
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 explains when to use lazy vs bundle modes, notes that mode is ignored for legacy projects and version overrides mode, and directs to haops_read_skill for fetching individual skill bodies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![haops-mcp-server MCP server](https://glama.ai/mcp/servers/tbranzov/haops-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/tbranzov/haops-mcp-server)

Score Badge

Copy to your README.md:

[![haops-mcp-server MCP server](https://glama.ai/mcp/servers/tbranzov/haops-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/tbranzov/haops-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tbranzov/haops-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server