AAP MCP Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have clear resource-action boundaries with consistent verb_noun naming, making them easy to tell apart. Minor overlaps exist between get_recent_activity and get_audit_logs (explicit alias) and among health/cluster/instance status tools, but these are not confusing enough to cause misselection.
Naming Consistency5/5
All tools follow a consistent aap_ verb_noun snake_case convention, with actions like list, get, create, update, delete applied uniformly across resources. Exceptions like add_user_to_team and get_job_output still fit within the established pattern.
Tool Count2/5
86 tools is far beyond the threshold where a toolset is considered well-scoped, making the surface feel heavy and harder to navigate. While AAP is a large platform, the sheer number of tools could overwhelm an agent and increase selection complexity.
Completeness3/5
The server covers many core workflows including project, inventory, job template, and workflow management. However, notable gaps exist: no get operations for inventories, hosts, groups, teams, schedules, or execution environments, and no list_groups or general job history listing. These are significant omissions for resources that otherwise have create/update/delete coverage.
Average 3.9/5 across 86 of 86 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 6 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safe read behavior is covered. The description adds only the return type ('str: JSON with team list') but discloses no other behavioral traits such as pagination defaults, filtering semantics, or potential errors.
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 extremely concise with a clear structure (action, args, returns). No verbose or redundant text, though it is under-specified. This earns a high score for conciseness, not for completeness.
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 a nested input object with three parameters and no schema descriptions, the description is too thin. It does not explain parameter meanings, default behaviors, or any edge cases, making it inadequate for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only says 'Pagination and filter' for the params object, which gives a high-level hint but does not explain the individual parameters (page, search, page_size) or their defaults and constraints.
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 states 'List AAP teams' which identifies the action (list) and resource (teams) clearly. It is unambiguous but does not explicitly differentiate from sibling list tools like aap_list_organizations or aap_list_users beyond the resource name.
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. The description only states the action and provides arguments/returns, with no mention of use cases, exclusions, or comparisons to sibling tools.
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?
Annotations indicate a non-read-only, non-destructive operation. The description adds the PATCH method and return format, but these are largely redundant given the output schema. It does not disclose error behavior, permission requirements, 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?
At two short lines, it is efficient and follows a standard Args/Returns structure, but the extreme brevity borders on under-specification.
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?
While the output schema covers return values, the description fails to explain parameter semantics or provide usage context for a tool that has five parameters, making it incomplete for reliable agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description merely says 'Fields to update' without elaborating on any of the five properties. This provides no semantic value beyond the schema names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' with resource 'AAP workflow template' and specifies the HTTP method PATCH, clearly distinguishing from sibling tools like aap_create_workflow_template or aap_delete_workflow_template.
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 states 'existing' implying the template must already exist, but provides no explicit when-to-use guidance or alternatives. It does not mention that this differs from aap_update_job_template or when to prefer this over create/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?
Annotations indicate readOnlyHint=false and destructiveHint=false, and the description does not contradict these. The description adds some behavioral context by clarifying it is a 'git pull' and that it returns a 'project_update_id for status tracking.' However, it does not disclose potential side effects, whether the sync is asynchronous, or any 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?
The description is well-structured with a purpose line, an Args section, and a Returns section. It is concise and avoids extraneous information. Each sentence serves a purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description is reasonably complete: it explains what the tool does, the input, and the return value. However, it omits potential prerequisites (e.g., the project must exist and have SCM configured) and does not point to the related status-checking tool. Overall, it is adequate but not richly contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description bears the burden of explaining parameters. It only restates 'project_id (int): Project ID to sync,' which adds no meaning beyond the schema's own description. It does not explain where to find the project ID, any required setup, or how the integer relates to project selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Trigger an SCM sync (git pull) for an AAP project.' This is a specific verb+resource combination. It does not explicitly differentiate from sibling tools, but there is no other tool that directly performs a project sync, so the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention the related sibling tool 'aap_get_project_sync_status' for checking sync status, nor does it state any prerequisites or exclusions. The usage context is implied solely by the tool's function.
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?
Annotations already convey that this is a non-read-only, non-destructive operation. The description adds that it uses PATCH and returns a JSON string with the updated project id and name, giving some behavioral context. However, it does not mention partial update semantics 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?
The description is concise, with a clear opening sentence and structured Args/Returns sections. The Args line is somewhat redundant given the schema, but overall it is efficient.
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 update operation and the presence of an output schema, the description is moderately complete. It explains the return value and the PATCH method, but lacks parameter semantics and usage context, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description merely refers to 'Fields to update' without explaining individual parameters, required project_id, or optional fields. This is insufficient to compensate for the lack of schema documentation.
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 'Update an AAP project (PATCH)', which is a specific verb and resource, and the PATCH method clarifies the operation type. It clearly distinguishes from sibling tools like aap_create_project, aap_delete_project, and aap_sync_project.
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 aap_create_project or aap_sync_project. The description simply states the act of updating without contextual hints or 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?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation nature is covered. The description adds the PATCH method and return format (id, name, next_run), providing some behavioral context, but it does not explain partial update semantics or potential 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 very concise and well-structured, with purpose, args, and returns in three clear sections, with 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?
For a simple update operation, the description covers purpose, input, and output, but the lack of parameter-level details and partial-update behavior leaves some ambiguity. The schema and return text carry much of the information, yet the description could have clarified whether omitted fields remain unchanged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description only says 'Fields to update' without explaining any individual parameters. This adds minimal meaning beyond the schema's field names and types, and does not compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing AAP schedule (PATCH)', naming the verb and resource specifically. It does not explicitly distinguish from sibling tools like aap_create_schedule or aap_delete_schedule, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only states what it does, with no exclusions or prerequisites, leaving the usage context entirely implied.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond the basic action. It does not mention idempotency, error behavior if the user is not on the team, required permissions, or any side effects, so it adds little beyond the annotations and the action 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 concise and follows a clear Args/Returns structure. It includes all essential information without redundancy, though the nested params block is slightly awkward and repeats schema field names.
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, the description covers the core operation, parameters, and return value. It lacks usage guidance and edge-case behavior, but the annotations and output schema provide additional context. This is adequate for a straightforward removal tool 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?
The schema has 0% description coverage, so the description's parameter list is important. It provides basic meanings for team_id ('Team ID') and user_id ('User ID to remove'), which slightly extends the schema titles. However, it does not add details about constraints, relationships, or expected values beyond what the field names imply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Remove a user from an AAP team') and resource, distinguishing it from siblings like aap_add_user_to_team and aap_remove_host_from_group. The verb is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention that it is the counterpart to aap_add_user_to_team or any prerequisites for removing a user from a team. It simply describes the operation without contextual usage direction.
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 annotations already indicate this is a write operation (readOnlyHint: false) that is not destructive (destructiveHint: false). The description adds the HTTP method (PATCH) and states the return format (JSON with updated credential id and name), providing some behavioral context. However, it does not disclose details about partial update behavior, idempotency, 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 appropriately short and front-loaded, with the main action stated first. It avoids unnecessary details but remains readable.
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 mutation tool with a nested input object and multiple fields, the description is sparse. It does not explain the meaning of 'inputs', whether fields are optional or required, or any operational constraints. The presence of an output schema reduces the need to describe return values, but the description still leaves key usage details undefined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only labels the param as 'Fields to update' without mentioning the actual fields (credential_id, name, inputs, description) or their semantics. Since schema description coverage is 0%, the description fails to compensate for the lack of parameter explanations, leaving the agent to rely solely on 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 updates an existing AAP credential via PATCH, specifying the verb and resource. It distinguishes itself from sibling tools such as create_credential, delete_credential, and get_credential. The mention of 'existing' clarifies the target object.
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 modifying an existing credential, but it does not provide explicit guidance on when to choose this tool over alternatives like create_credential or delete_credential. There are no examples, prerequisites, or exclusions, so the usage context is only implied.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the HTTP method 'PATCH', which conveys partial-update semantics and non-destructive behavior consistent with annotations. It does not add details about required permissions, idempotency, or what happens to omitted fields, but the existing annotations lower 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with one purposeful sentence and an Args block. It avoids fluff and is well-structured. However, it is so brief that it sacrifices utility in parameter documentation, though that is reflected in other dimensions.
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 0% schema coverage, minimal annotations, and no explanation of partial-update semantics or required identifiers, the description is incomplete for safely invoking the tool. An output schema exists, which helps with return values, but the description fails to provide essential context about how to properly update an execution environment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It only says 'params (UpdateEEInput): Fields to update,' which adds no meaning beyond the schema's field names and types. It does not explain the purpose of 'pull' or clarify that 'ee_id' identifies the target resource. This is a significant gap.
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 an existing AAP execution environment') with a specific verb and resource. It also mentions 'PATCH', which adds precision. This distinguishes it from sibling tools like aap_create_execution_environment and aap_delete_execution_environment.
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 by saying 'Update an existing...' but does not explicitly state when to use it versus alternatives (e.g., create or delete). It does not provide exclusions or prerequisites beyond 'existing'. The context is clear but not explicit.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that this is a PATCH operation and returns JSON with updated group id and name. It does not disclose edge-case behavior like whether null fields clear values or if variables must be YAML, so it provides only modest additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. The Args/Returns structure is standard and wastes no words. It could be slightly more informative without losing conciseness, but it is efficient.
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 0% schema description coverage and no output schema, the description is too thin for a tool with four parameters. It lacks parameter semantics, usage rules, and behavioral details such as what happens to existing fields when omitted. The description only covers the basic purpose and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the lack of field-level documentation. It only says 'params (UpdateGroupInput): Fields to update,' which restates the obvious and provides no meaning beyond the schema's field names. It does not clarify group_id, variables, or description formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update an existing AAP inventory group') with the HTTP method (PATCH). It clearly identifies the resource type (inventory group) and distinguishes it from create/delete operations 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 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. It does not mention prerequisites, exclusions, or compare with related tools such as create_group or delete_group. The only implicit usage is 'update an existing group,' which is not enough.
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?
Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false (non-destructive). The description adds no extra behavioral context such as idempotency, permission requirements, or side effects. The mention of 'Returns: str: JSON with created schedule id, name, and next_run' is return value info, not behavioral disclosure, so it does not meaningfully enhance transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-structured docstring with a clear purpose statement, parameter list, and return value. No fluff or redundant text; every sentence provides value in a compact format.
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 covers the primary action and return type but lacks important context: it does not mention required parameters (name, unified_job_template_id, rrule) which are only in the schema, omits the 'description' parameter, and gives no guidance on recurrence rule syntax beyond the schema. Given the tool's complexity (6 parameters, nested input), the description is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It lists and explains most parameters (name, unified_job_template_id, rrule, enabled, extra_vars) where the schema lacks descriptions for some (e.g., enabled). However, it omits the 'description' parameter entirely, and the explanations are brief, not fully compensating for the 0% 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 'Create a schedule for an AAP job template or workflow' - a specific verb ('Create') and resource ('schedule') that distinguishes it from sibling tools like update_schedule, delete_schedule, and list_schedules. No ambiguity about its 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. It does not mention that update_schedule should be used for modifying existing schedules or list_schedules for viewing them. Sibling names exist but are not referenced, leaving the agent without explicit 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is known. The description adds the context that this is an 'audit trail of changes' and that the return is a JSON string with activity events. However, it does not disclose pagination behavior, ordering, or potential rate limits. This is acceptable given the annotations.
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: a single lead sentence plus a structured Args/Returns block. It is front-loaded with the core purpose and the parameter list is easy to scan. Slight redundancy with schema descriptions exists, but it does not waste 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 is a simple read operation with an output schema and annotations, so the description need not explain return values in depth. However, it lacks guidance on how it differs from aap_get_audit_logs, and 'recent' is not quantified. The filter options are covered, but the overall context of when this is the right tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The top-level schema has 0% description coverage, but the description's Args section compensates by listing all inner parameters (limit, operation, object_type, username) with brief meanings. The schema itself provides descriptions for three of these, but the description adds the 'Number of events' semantics for limit, which is missing in the schema. This goes beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Get recent AAP activity stream (audit trail of changes).' It clearly identifies the tool as a read operation for recent activity events. While it doesn't explicitly distinguish itself from the sibling tool 'aap_get_audit_logs', the purpose is specific and not a tautology.
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 is given about when to use this tool versus alternatives like aap_get_audit_logs. The description implies usage for recent activity but does not state exclusions, prerequisites, or when another tool might be more 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the mutation is clear, but the description adds little beyond that. It only mentions the return type and does not disclose idempotency, error conditions, required permissions, or behavior if a host already exists. With annotations present, the bar is lower, but the description still lacks meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with a clear opening statement, a helpful example, and a brief args/returns section. It is not overly verbose, though the example could be more aligned with the actual parameter semantics.
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 having an output schema and annotations, the description is incomplete for a create tool. It does not explain how to obtain the required inventory_id, and the example uses an inventory name instead of an ID, which is inconsistent with the schema. It also omits prerequisites like the inventory needing to exist. These gaps make the description insufficient for reliable tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description merely restates 'params (CreateHostInput): Host configuration' without explaining any individual parameters. Schema description coverage is 0%, so the description should compensate but does not. The example mentions 'Production inventory' which conflicts with the required integer inventory_id, potentially misleading the agent. Although the schema has property descriptions, the description adds no value beyond them.
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 starts with 'Add a host to an AAP inventory' which is a specific verb+resource and clearly differentiates from siblings like aap_create_inventory or aap_add_host_to_group. The example reinforces the action by showing a concrete hostname and inventory context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (when adding a host to an inventory) through its opening sentence and example. However, it does not explicitly state exclusions or mention alternative tools like aap_update_host or aap_add_host_to_group, so it falls short of a full 5 but provides clear 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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the scope (controller and execution nodes) and return type, but does not disclose potential behaviors like pagination, authentication requirements, or the structure of the returned JSON. It provides modest additional context beyond the annotations.
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 short sentences, front-loaded with the purpose and a brief return note. No unnecessary words, though the 'Returns:' line is somewhat redundant given the output schema. Overall, it is appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with read-only annotations and an output schema, the description provides adequate context about what is listed and the return type. The main gap is the unexplained required 'params' parameter, but this does not detract significantly from the overall clarity for a straightforward listing operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'params' which is an empty object (HealthInput with no properties), and schema description coverage is 0%. The description does not mention this parameter at all, leaving the agent unaware that a required 'params' object must be passed (even if empty). There is no compensation for the missing schema descriptions, so parameter semantics are completely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb and resource: 'List all AAP controller and execution node instances.' It fully distinguishes this from sibling list tools (e.g., aap_list_organizations, aap_list_users) by explicitly naming the resource type and its 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 implies usage for listing instances but provides no explicit guidance on when to choose this tool over alternatives like aap_get_instance_capacity or aap_get_controller_health. It does not state exclusions or prerequisites, so usage context is only implied.
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?
Annotations already provide readOnlyHint=false and destructiveHint=false, so no contradiction. The description adds the PATCH method and return format ('JSON with updated host id and name'), but does not disclose other behavioral aspects like required permissions, error handling, or whether omitted fields are left unchanged. This adds some value beyond annotations but not substantial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise and well-structured: a single purpose sentence followed by a docstring-style Args/Returns block. It front-loads the key information and contains no unnecessary words, though it could be slightly longer to include parameter explanations.
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 involves a nested input schema with five parameters, yet the description provides minimal context beyond the purpose. It does not explain parameter semantics, update behavior for omitted fields, or any prerequisites (e.g., that host_id must exist). The return value is specified, but overall the description is insufficient for confident, correct usage without additional schema documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only states 'Fields to update' without listing or explaining the parameters (name, enabled, variables, description). The schema provides types and defaults but not meanings (e.g., that 'variables' as a string likely contains YAML/JSON), leaving the agent with insufficient guidance.
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 an existing AAP host (PATCH)'), identifies the resource (AAP host), and specifies the HTTP method. This distinguishes it from sibling tools like aap_create_host, aap_delete_host, and aap_list_hosts.
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 phrase 'existing AAP host' implies the tool is used for modifying an already-created host, but there is no explicit guidance on when to use this versus aap_create_host or when not to use it. Alternatives are not mentioned, leaving usage context mostly implied.
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 the return format ('JSON with created template id, name, and launch URL') and provides an example with become/check flags. However, it does not disclose idempotency, failure behavior, or other side effects beyond creation.
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 and well-structured with purpose, example, args, and returns sections. It is front-loaded with the main verb and 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?
For a create tool with many parameters, the description gives an example and return info but lacks guidance on when to use it vs update/copy and does not mention required relationships like existing project and inventory. The schema provides field-level detail, so it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only points to 'See field descriptions' without summarizing or explaining parameters. With 0% schema description coverage in the description, it fails to compensate for parameter understanding 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 'Create a new AAP job template' with a specific verb and resource. It distinguishes the tool from sibling tools like update, delete, list, and launch.
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 through an example but does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like existing projects or inventories.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds the return value (JSON with created user id and username). However, it does not disclose permissions, uniqueness checks, or failure behavior, leaving gaps in behavioral 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 and well-structured with Args and Returns sections. It avoids unnecessary wording, though it could include more detail without harming 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?
For a simple create operation, the description provides the essential return type and purpose. However, it lacks context on prerequisites, error handling, or relations to other user management tools, making it only moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% because the description only says 'params (CreateUserInput): User details' without explaining individual fields. The schema provides some descriptions, but several properties like last_name, first_name, is_superuser lack clarity, and the description does not compensate.
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 AAP user' with a specific verb and resource, distinguishing it from sibling tools like update, delete, or list. This is unambiguous.
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 tool's purpose implicitly indicates when to use it (to create a user), but there is no explicit guidance on alternatives or conditions, such as using update for existing users. Minimal usage context is 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?
The annotations already indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds that the return is a JSON string containing instance capacity and health, which is useful context. However, it doesn't mention pagination, error conditions, or any specific fields beyond 'list of instances and their capacity/health'.
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 purpose is front-loaded, and the return type is stated separately. No unnecessary wording.
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-only status tool with annotations and a clear return description, this is adequately complete. It could benefit from clarifying how it differs from related health/capacity tools, but that gap is more about usage guidance than completeness. The tool has a clear output schema (not shown but present), reducing the need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single 'params' object with no properties, making this effectively a parameterless tool. The description provides no parameter details, but none are needed. The schema itself is self-explanatory. Since there are no meaningful parameters, this is adequate.
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 it retrieves AAP cluster node status, capacity, and health summary. It uses a specific verb ('Get') and specifies the resource. However, it doesn't explicitly distinguish this from sibling tools like aap_get_controller_health or aap_list_instances, which might serve similar purposes.
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 aap_get_controller_health or aap_get_instance_capacity. The description only states the function, leaving the agent to infer appropriate usage.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by explaining what execution environments are and describing the return payload (JSON with id, name, image, managed status), which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the purpose and followed by a return summary. Every word earns its place, with no fluff 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?
While the tool is a simple read-only list, the description omits important behavior around pagination and search (which are represented by the parameters). It does not mention that results are paginated or how search works, so the description is not complete enough given the schema lacks parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the three parameters (page, search, page_size). The parameters are not self-evident regarding pagination or search behavior, and the description makes no effort to compensate for the schema's lack of documentation.
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 AAP execution environments and defines them as container images for job execution. This precise verb-resource pairing distinguishes it from sibling tools like create/update/delete EE 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when you need to list execution environments. However, it does not explicitly mention when not to use it or propose alternatives. Since there is no get_execution_environment sibling, the list operation is the obvious read path, but guidance is not explicit.
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?
Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, which cover the basic mutation/side-effect profile. The description adds the return format (JSON with created organization details including id), but does not disclose potential failure modes, permission requirements, or duplicate handling. It adds some behavioral context but not rich detail.
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 Args and Returns sections, front-loaded with the main purpose. It is reasonably concise, though the parameter details are somewhat redundant with the schema. Overall it is efficient and scannable.
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 create tool, the description covers the main purpose and return format, and annotations provide mutation/idempotency hints. However, it lacks guidance on prerequisites (e.g., admin permissions), failure conditions (e.g., duplicate name), or how to handle errors. These gaps are notable 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?
The schema already provides descriptions for each field (name, description, max_hosts), including constraints like maxLength and default values. The description's Args section repeats these field names and types without adding new semantic meaning. The 'Optional' label for description is already implied by schema defaults. Minimal added value 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 explicitly states 'Create a new organization in Ansible Automation Platform' with a clear verb ('Create') and resource ('organization'). It clearly distinguishes from sibling tools like list, get, update, and delete by indicating it creates a new 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?
The usage is implied by the verb 'Create' and the absence of explicit alternatives. No mention of when to use this versus other organization tools, nor any prerequisites or exclusions. It is clear only in the most basic sense.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read nature is covered. The description adds useful behavioral context by stating the return format (JSON string) and key fields (rrule, next_run, linked template), and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose, followed by compact Args and Returns sections. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with annotations and an output schema, the description is minimally adequate. However, it omits usage guidance (e.g., no mention of when to list versus create/update/delete schedules) and leaves parameter semantics mostly to inference, creating clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only says params are 'Pagination and filter options,' which is a high-level grouping, but it fails to define what 'search' matches, how 'enabled' filters, or any other per-field semantics. The field names are somewhat guessable, but this is not enough for zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('AAP schedules'), and clarifies scope with 'for jobs and workflows.' This clearly distinguishes it from sibling schedule mutation tools like aap_create_schedule, aap_update_schedule, and aap_delete_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or point to sibling tools for creating/updating/deleting schedules; the only usage context is the implied 'use this to list schedules' from the name and first line.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description adds the PATCH method and return format (JSON with updated id/name). However, it does not clarify how null fields are handled or whether permissions are required, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with a clear one-line summary followed by concise Args/Returns sections. No redundant information is present.
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 CRUD update with annotations and an output schema, this is minimally adequate. However, it omits important context about optional field semantics, especially how to indicate 'do not update' versus 'clear this field,' and the nature of the 'variables' field is left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only refers generically to 'Fields to update.' It does not explain that inventory_id is required, that fields like variables or description are optional, or what values such fields accept. This forces the agent to rely on inference from names and types alone.
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 an existing AAP inventory using PATCH, which distinguishes it from sibling tools like delete_inventory or create_inventory. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when modifying an existing inventory, but it does not explicitly mention alternatives or state when not to use this tool. The word 'existing' provides limited guidance, but no direct comparison to sibling tools is 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?
Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds the HTTP method (PATCH) and a note that it returns JSON with updated user id and username, which is useful but does not disclose permissions, error handling, or idempotency 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 concise: one sentence for purpose, then Args/Returns sections with minimal, clear text. No filler or redundant information, and the key action is 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?
The description covers the essential purpose and return format, and an output schema exists. However, it does not elaborate on field semantics, constraints, or edge cases, leaving the agent to infer details from the input schema. This is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only says 'Fields to update' without listing or explaining the individual parameters. The schema itself lacks descriptions for most fields, so the description fails to compensate for the lack of 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 updates an existing AAP user via PATCH, specifying the verb, resource, and method. This unambiguously distinguishes it from sibling tools like aap_create_user, aap_get_user, and aap_delete_user.
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 phrase 'existing AAP user' implies this is for modifying already-created users, but there is no explicit guidance on when to prefer this over alternatives like aap_create_user or aap_get_user. No exclusions or alternative conditions 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?
Annotations already signal a non-read-only, non-destructive operation. The description adds that it returns JSON with id and name, but does not disclose details like registry pull behavior, credential requirements, or failure modes. Reasonable but minimal added 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?
Efficient and well-structured: a clear one-line purpose followed by an Args/Returns block. No redundancies or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested params object, but the input schema thoroughly documents all fields and the output schema specifies the return type. The description adequately covers the operation's core purpose and return value, so the overall context is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only says 'params (CreateEEInput): EE configuration', which adds no meaning beyond the schema's rich per-field descriptions. With schema description coverage at 0%, the description fails to compensate by explaining how fields relate or how to construct the configuration.
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 states verb 'Create' + resource 'AAP execution environment' + key attribute 'referencing a container image'. This clearly distinguishes it from update/delete/list execution environment siblings.
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 when creating a new execution environment, but provides no explicit when-to-use guidance, prerequisites, or exclusions against alternatives like update/delete. Sibling names hint at the distinction, but the description itself does not.
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?
Annotations already indicate a non-read-only write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds the return format (JSON with project id, name, initial status) and the Git/SCM origin, but does not disclose side effects like whether a project sync is triggered or permission requirements.
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: a one-sentence purpose, a helpful example, and clearly labeled Args/Returns sections. Every line earns its place, and the structure is immediately 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?
The description covers the core purpose, provides an example, and states the return shape. With an output schema present, return-value details are not the description's burden. Combined with the schema's rich parameter descriptions, this is mostly complete, though it lacks guidance on manual (non-SCM) projects and post-creation behavior like syncing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only says 'params (CreateProjectInput): Project configuration' with 0% coverage of the 9 nested properties. The input schema has detailed per-property descriptions, but the description itself does not compensate. The example hints at name and scm_type only, leaving other fields (scm_clean, credential_id, organization_id, etc.) unexplained 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 opens with a clear verb+resource+source: 'Create a new AAP project from a Git/SCM repository.' The example ('Create a new project called redis-automation from GitHub') reinforces the purpose and distinguishes this from sibling create_* tools like aap_create_organization or aap_create_inventory.
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 concrete example, implying the tool is used for creating source-controlled projects, but it does not explicitly state when to use this tool versus alternatives (e.g., manual projects via scm_type=''). No exclusions 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it returns a string in JSON format, but provides no additional behavioral context such as error handling, authentication requirements, or what happens if the user ID does not exist. This is acceptable for a simple read-only get tool, but the description does not go beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a clear one-sentence purpose followed by an 'Args' section and a 'Returns' line. It avoids unnecessary wording and is easy to scan.
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-by-id tool with one parameter, read-only annotations, and a stated JSON return format, the description is nearly complete. It could be improved by noting error behavior (e.g., 404 if user not found) or what fields are included in the JSON response, but with no output schema visible, the description gives enough for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (user_id) with a description 'User ID', type integer, and minimum 1. The description repeats 'user_id (int): User ID' without adding any new meaning such as how to obtain the ID, its format beyond int, or domain-specific context. With schema description coverage at 0% according to context signals, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get details of a specific AAP user by ID.' It uses a specific verb ('Get'), names the resource ('AAP user'), and indicates the key identifying parameter ('by ID'), which distinguishes it from sibling tools like aap_list_users or aap_update_user.
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 usage is implied: it is for retrieving a single user by their ID. However, the description does not explicitly contrast with alternatives (e.g., use aap_list_users to search or list users) or provide any when-to-use / when-not-to-use guidance. The context is clear from the tool name, but no 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag read-only and non-destructive, but the description adds that secrets are never returned and are masked by AAP, plus the return format. This is useful context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the purpose. Args and Returns sections are clearly structured with no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with a read-only annotation and output schema, the description covers purpose, arguments at a high level, return format, and the masking behavior. It would benefit from explicit alternative references, but is otherwise adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only labels params as 'Pagination and filter options' without detailing individual fields. Schema description coverage is 0% for the top-level parameter, so the description fails to compensate by explaining page, page_size, search, or credential_type 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?
Description clearly states the tool lists AAP credentials, distinguishing it from credential detail/modify tools. The verb 'List' and resource 'AAP credentials' are specific, and the note about secrets never being returned adds scope.
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?
Description provides no guidance on when to choose this over sibling tools like aap_get_credential or aap_list_credential_types. It only mentions pagination/filter options without referencing alternatives or exclusion criteria.
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 return value is a JSON string with a count and workflow template list, which is useful. It also indicates that the params object handles pagination and filtering. However, it does not elaborate on search semantics, pagination behavior, or other operational details. Since annotations already flag this as read-only and non-destructive, the description adds modest context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a one-sentence purpose followed by a structured Args/Returns block. There is no redundancy or filler, and the main purpose is front-loaded in the first sentence.
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, the description covers the purpose, return format, and the high-level parameter purpose. However, it omits details like how search filtering works, pagination defaults, and error scenarios. While the output schema (not shown here) may compensate, the description alone provides only a basic, though not incomplete, picture.
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 0% description coverage for the nested fields, so the description's line 'params (ListWFTInput): Pagination and filter' provides high-level meaning for the parameter. It does not explain individual fields like page or search, but the schema already provides names, types, defaults, and constraints. The description offers minimal added value 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 'List AAP workflow job templates', which clearly specifies the action (list) and the resource (workflow job templates). This differentiates it from the sibling tool aap_list_job_templates, which lists regular job templates, by explicitly naming the workflow aspect.
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 over alternatives like aap_list_job_templates. Usage is implied by the resource name, but there is no mention of when to choose this tool, any exclusions, or recommended alternative tools. The absence of explicit guidance makes it merely adequate.
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?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds minor context: where to source role IDs and that it returns a JSON confirmation string. It does not disclose side effects like idempotency or required permissions, but given the annotation coverage, it crosses the minimum threshold.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose, and uses a clear Args/Returns structure. Every line contributes, with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple role-assignment tool, the description covers the essential invocation details: parameters and return type. It could mention idempotency or required permissions, but the annotations and schema already cover safety and parameter needs. The output schema is marked as present, so the return string is sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already includes descriptions for user_id and role_id, including the hint to get IDs from resource role endpoints. The tool description repeats this information nearly verbatim, adding minimal value beyond packaging the two parameters under 'params'. The extra clarity of naming the assignment source is redundant with 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 opens with 'Assign an RBAC role to an AAP user', which clearly states the verb, resource, and scope. It distinguishes from sibling tools like aap_revoke_role and add/remove user to team.
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 when to use this tool by naming the action, but it does not explicitly mention alternatives or exclusions. The hint about role IDs from /api/v2/roles/ or resource role lists provides a partial context, but there's no clear 'use this for granting, use revoke_role for removing' 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with a create operation. The description adds the return format ('JSON with created credential type id and name'), providing some behavioral context. However, it does not disclose any side effects beyond creation, such as validation requirements or impact on existing credentials. The added value is modest but not contradictory.
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 an 'Args' section and a 'Returns' note, each line providing essential information. It is concise, with no redundant or filler text, and earns its place by explaining parameters and the return value clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a create operation with a straightforward purpose. The description, combined with the schema's property examples and the presence of an output schema, covers the core functionality. It lacks some contextual details like prerequisites or when to choose this over built-in credential types, but given the moderate complexity and available structured data, 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?
Given schema description coverage is 0%, the description carries the burden of explaining the 'params' object. It lists four key fields (name, kind, inputs, injectors) with brief semantic hints, complementing the schema's property definitions. However, it omits the optional 'description' field present in the schema and does not fully detail the structure of inputs/injectors beyond what the schema examples already offer. It partially compensates but is not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a custom AAP credential type with custom fields and injectors,' which uses a specific verb and resource. It distinguishes this from sibling tools like aap_create_credential (which creates a credential instance) and aap_list_credential_types (which reads existing types). The purpose is unambiguous.
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 creating custom credential types but does not explicitly state when to use it versus alternatives. No exclusions or alternative tool references are provided, leaving the agent to infer the appropriate context from the tool name and description. This 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the return format (JSON with group id and name) but provides no further behavioral context such as idempotency, error conditions, or permissions. This is minimal added value beyond annotations.
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 and front-loaded with the primary purpose. The Args/Returns structure is clear and efficient, though the Args line is somewhat redundant with the schema. Overall, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation, the description provides the essential purpose and return type. It does not discuss alternatives or prerequisites, but the schema covers the required fields (name, inventory_id). The presence of an output schema further reduces the need to describe return values in detail, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description merely states 'params (CreateGroupInput): Group configuration,' which adds no meaning beyond the input schema. Schema description coverage is 0% for the tool description, and it does not compensate for the lack of parameter explanations; the schema itself provides some detail, but the description fails to 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 with a specific verb and resource: 'Create a host group inside an AAP inventory.' This distinguishes it from sibling tools like aap_update_group, aap_delete_group, and aap_add_host_to_group, leaving no ambiguity about what the tool does.
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 clear context: creating a host group within an AAP inventory. It does not explicitly mention alternatives or exclusions, but the purpose is straightforward and self-evident, making it easy for an agent to know when to invoke 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?
Annotations already declare readOnlyHint=false and destructiveHint=false, matching the create action. The description adds the return format (JSON with created team id and name) but does not disclose additional behavioral traits such as required permissions or idempotency. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and uses a clean Args/Returns structure with no filler. Every sentence contributes useful 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 create operation, the description covers the action, inputs, and output. The return format is specified. It could mention that the organization must exist, but the organization_id parameter implicitly covers this. Overall, it's complete for the tool's 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?
The schema has 0% field descriptions, but the description's Args section enumerates the three fields: 'Team name, organization_id, description.' This adds minimal meaning beyond the schema, clarifying the intent of the nested params object, but it does not explain constraints or relationships 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 'Create a new AAP team within an organization,' using a specific verb and resource. It distinguishes itself from sibling tools like aap_update_team and aap_delete_team by focusing solely on creation. The return type is also mentioned.
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 usage is implied by the verb 'Create' and context 'within an organization,' but the description does not explicitly discuss alternatives or exclusions (e.g., when to use aap_update_team instead). It lacks explicit when-not-to-use guidance, so it's adequate but not strong.
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?
Annotations already mark this as destructive (destructiveHint=true). The description adds the explicit warning 'DESTRUCTIVE - requires confirmation', reinforcing the irreversible nature and hinting at a confirmation mechanism, which annotations do not convey. However, it doesn't detail what the confirmation entails or the effects beyond deletion.
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 resource, with a clear destructive warning. No redundant words or unnecessary details.
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 destructive tool with a confirmation mechanism, the description is underspecified. It doesn't clarify the confirmation workflow, prerequisites, or what happens if the token is invalid. The existence of an output schema mitigates return-value concerns, but the operational context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter explanations. The schema only exposes 'ee_id' (integer) and 'confirmation_token' (nullable string) with no descriptions. The description's 'requires confirmation' hints at the token's purpose but doesn't explain how to obtain or use it, leaving parameter semantics largely to inference.
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 the specific verb 'Delete' and resource 'AAP execution environment', clearly distinguishing it from sibling delete tools targeting other resource types (e.g., workflow templates, hosts). The action and target are unambiguous.
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 is given about when to choose this tool over alternatives, though the resource-specific name makes the target clear. The 'requires confirmation' note implies a safety protocol but doesn't explain how to invoke it or prerequisites. This is minimal but not misleading.
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?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds the critical two-step confirmation flow via the 'confirmation_token: Token from first call' comment. This goes beyond the annotation by revealing that the tool behaves in two phases. No contradiction 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?
The description is compact: a one-line action, a clear 'DESTRUCTIVE' warning, and a simple parameter list. Every sentence earns its place—no fluff, and the most important warning 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 two-parameter delete tool, the description adequately covers the core behavioral aspect (confirmation token flow) and the object being deleted. It does not explain what the first call returns (presumably a token) or how to obtain the schedule_id, but given the tool's simplicity and the presence of an output schema, it remains 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 description coverage is 0%, so the description must compensate. It identifies both parameters: schedule_id is given a basic 'Schedule ID' description (matching the schema title), while confirmation_token is explained as 'Token from first call', adding crucial semantic context. However, schedule_id lacks guidance on how to obtain it or constraints, leaving the compensation incomplete.
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 'Delete an AAP schedule.' which is a specific verb+resource (delete + schedule) and clearly differentiates from sibling tools like aap_update_schedule or aap_delete_workflow_template. It also adds a loud 'DESTRUCTIVE' warning, reinforcing the delete action.
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?
There is no guidance on when to use this tool versus alternatives (e.g., when to update a schedule instead of deleting it, or how this differs from canceling a job). The 'requires confirmation' hint is a process note, not a selection guideline. A clearer statement such as 'Use this to permanently remove a schedule; use update_schedule to modify or disable' is absent.
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?
Annotations already mark the tool as destructive, but the description adds valuable context: a confirmation token is required from a first call, indicating a two-step confirmation workflow. This goes beyond the structured hints and clarifies expected 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 concise and front-loaded with the purpose and a clear DESTRUCTIVE warning, followed by a compact parameter list. Every line contributes necessary information without waste.
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 destructive tool, the description omits a critical workflow detail: the first call likely returns a confirmation_token, and a second call is required to complete the deletion. The phrase 'Token from first call' is insufficient for an agent to confidently execute the two-step process; the description is incomplete for safe 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?
The description lists both parameters with brief annotations, and 'Token from first call' adds meaning beyond the schema's bare title. However, it does not explain how to obtain the token or the format expected, so the added value is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete an AAP user,' a specific verb and resource, clearly distinguishing it from sibling delete tools by naming the target. It also flags the destructive nature, which adds precision.
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 that deletion requires confirmation and mentions a token from the first call, implying a two-step process. However, it does not explicitly compare to alternative tools or state when not to use this tool, leaving usage guidance thin.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context by stating the return type ('str: JSON') and that it returns 'full project details', which goes beyond the annotations. It does not discuss error handling or not-found behavior, but for a read-only getter with annotations, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary purpose. The Args and Returns sections are useful, though the Args section duplicates schema information. It earns a 4 because it is concise without excess, but the param documentation could be trimmed.
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-only get operation with an output schema available, the description covers the essential purpose and return format. However, it lacks any usage guidance or detail about what 'full details' means, which would improve completeness. Given the low complexity, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it merely repeats the schema's 'project_id (int): Project ID' without adding any new meaning, such as how to find the project ID or what fields the full details include. This is redundant rather than informative.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get full details of an AAP project,' which uses a specific verb ('Get'), a clear resource ('AAP project'), and specifies scope ('full details'). This clearly distinguishes it from sibling tools like aap_list_projects, which presumably returns summaries, and aap_update_project/aap_delete_project, which perform mutations.
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 when you need full details of a single project, but it does not explicitly state when to use this tool versus alternatives like aap_list_projects or aap_get_project_sync_status. No exclusions or when-not-to-use guidance 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the endpoint '/api/automation-hub/v3/' and return format 'str: JSON', which are useful context beyond annotations. No contradictory behavior is disclosed.
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 compact paragraph with separate Args and Returns sections. Every sentence contributes purpose, a prerequisite, and return info. No redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description covers purpose, API access requirement, and return type. The input schema provides parameter details, and annotations cover safety. It lacks explicit pagination behavior, but the schema defaults and descriptions are sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only says 'params (ListCollectionsInput): Pagination and filter.' It does not explain the individual fields like page, search, namespace, or page_size. With schema coverage at 0%, the description should compensate, but it only provides a high-level grouping.
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 Ansible collections in Automation Hub' – a specific verb, resource, and location. This clearly distinguishes from sibling list tools like aap_list_projects or aap_list_inventories.
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 the agent needs collections from Automation Hub, and the API-access note provides a prerequisite. However, it doesn't explicitly state when not to use it or mention alternatives, though the context is clear enough.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the return format (JSON with count and inventory list including id, name, description, total_hosts, groups_with_active_failures) and mentioning pagination/filter options, which goes beyond the annotations. No contradictions found.
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 a clear front-loaded purpose, followed by compact Args/Returns sections. Every sentence earns its place, and there's no redundant 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?
The tool is simple and the return format is described, but the description lacks detail on parameter semantics and scope of the listing (e.g., whether it returns all inventories or requires an organization filter). The output schema is not provided, but the description does enumerate the returned fields. Overall, it's minimally adequate but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only says 'Pagination and filter options' without explaining the individual properties (page, search, page_size, organization). This provides a general hint but doesn't add field-level meaning, making it hard for the agent to know what each parameter does.
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 AAP inventories' with a specific verb and resource, distinguishing it from sibling tools like aap_create_inventory, aap_update_inventory, and aap_delete_inventory. The Returns section also clarifies the output contains a count and inventory list with key 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 as a list operation but provides no explicit guidance on when to use it versus alternatives (e.g., when to use aap_export_inventory for exports or aap_list_hosts for hosts). The 'Pagination and filter options' hint gives some context, but there's no when-not-to-use or alternative tool references.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool returns a JSON confirmation string, but it doesn't disclose idempotency, failure behavior, or side effects. No contradiction 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?
The description is two short sentences, clearly structured with Args and Returns. It front-loads the primary verb and resource, and every word serves a purpose with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with an output schema, the description provides all necessary information to select and invoke it correctly. It could add preconditions or edge cases, but they are not essential for this straightforward revoke action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully specifies both parameters with types and minimum values. The description's parameter list adds minimal extra meaning (e.g., 'Role ID to revoke'), but it essentially restates schema info. Since schema coverage is high, 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 opens with a specific verb ('Revoke') and resource ('RBAC role from an AAP user'), clearly distinguishing it from sibling tools like 'aap_assign_role' and 'aap_remove_user_from_team'. It states exactly what action is performed without ambiguity.
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 usage is implied: use this tool when you need to remove an RBAC role assignment from a user. There is no explicit when-not or alternative guidance, but the sibling context makes it obvious that this is the inverse of 'aap_assign_role'.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, and the description aligns by stating 'Add' and returning a JSON confirmation. However, the description does not reveal whether the operation is idempotent (e.g., what happens if the host is already in the group) or any error behaviors. It does not contradict annotations, but it adds limited behavioral context beyond the structured data.
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 short and includes an Args section and a Returns section, making the action and inputs clear at a glance. It is front-loaded with the main sentence, but the Args section slightly duplicates parameter descriptions already present in the schema. Overall, it is efficient and well-structured for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward add operation, the description covers the action, parameters, and return type. It does not mention potential constraints such as requiring the host and group to be in the same inventory, nor error handling, but the operation's simplicity and non-destructive annotations reduce the need for extensive detail. The description is sufficient for an agent to invoke the tool with the correct IDs.
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 top-level input schema has a single 'params' object with 0% description coverage, but the description explains the nested structure and lists group_id and host_id with brief meanings. While the nested schema properties already have descriptions, the description clarifies the wrapping and provides a clear mapping to the expected input, adding value beyond the schema at the top level.
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 'Add an existing host to a group within an inventory,' using a specific verb and resource. This clearly distinguishes it from sibling tools like aap_remove_host_from_group, making the tool's 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some context by specifying 'existing host' and 'within an inventory,' implying prerequisites, but it does not explicitly compare to alternatives or state when to use this tool over others. No exclusions or sibling references are provided, though the purpose is straightforward enough for an agent to infer basic 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the description does not contradict them. The description adds that the operation returns a new template id and name, but it does not disclose side effects such as whether associated permissions or credentials are copied. It provides basic transparency but not deep 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured with an Args/Returns format, making it easy to scan. It uses minimal sentences without unnecessary filler, though the formatting could be slightly tighter.
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 two-parameter copy operation, the description covers what the tool does, the parameters, and the return value. It is sufficiently complete for its complexity, though it could mention whether all source template settings are preserved or if any fields are excluded from the copy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage reported as 0%, the description compensates by listing both parameters and their meanings: 'template_id (int): Source template ID' and 'name (str): Name for the copy'. This provides functional semantics beyond the raw schema, though it lacks examples or edge-case 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 clearly states the action: 'Copy an existing job template with a new name.' This is a specific verb ('Copy') and resource ('job template') with a clear outcome. It is easily distinguished from sibling tools like create, update, delete, or launch.
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 usage scenario (duplicating a template with a new name) but does not explicitly contrast it with alternatives like aap_create_job_template. It gives a clear context for use but omits explicit when-to-use/not-to-use guidance or exclusions.
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 the return format ('JSON with created inventory id and name'), which adds behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false). It also gives a concrete example, improving transparency for a simple create 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 compact and well-structured, including a purpose line, an example, args, and return format in just a few sentences. Every part earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward create tool with an output schema and annotations, the description covers the core action and return value sufficiently. It could mention error behavior or idempotency, but those are not essential for a simple create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only labels the parameter as 'params (CreateInventoryInput): Inventory configuration,' which adds no detail about required fields like name and organization_id or optional fields like kind and variables. With schema description coverage at 0%, the description fails to compensate.
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 'Create a new AAP inventory' with a clear verb and resource, and gives an example that demonstrates the intended usage. It is distinct from sibling tools like aap_list_inventories, aap_update_inventory, and aap_delete_inventory, so the purpose is unambiguous.
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 ('Create a new inventory') but provides no explicit when-to-use or when-not-to-use guidance, nor does it reference alternative tools. The example is helpful but does not contrast with update or delete operations.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool creates a template without nodes ('After creation, use the AAP UI or API to add workflow nodes') and returns a JSON with id and name. This goes beyond the annotation hints, though it doesn't cover permissions 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?
The description is concise, with a clear structure: one-line purpose, example, note, and Args/Returns sections. No redundant sentences. The note about adding nodes is valuable and earns its place. Slightly more detail on parameters could be added without bloat, so a 4.
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 6 sub-fields and no output schema. The description covers the main purpose, the return format, and a key limitation (nodes must be added later). However, it doesn't mention prerequisites (e.g., organization assignment) or typical fields to set, and the schema descriptions are sparse. This is adequate for a simple create but leaves some gaps for a complex workflow template.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only labels the parameter as 'Workflow template configuration' and does not explain any of the subfields (e.g., extra_vars, organization_id, survey_enabled). The example hints at real-world usage but doesn't clarify how parameters map to the example. This leaves the agent to rely solely on field names and types, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create a new AAP workflow template.' The example ('Create a workflow that provisions EC2 and configures Apache') gives a concrete use case, and the name differentiates from sibling tools like update, delete, and launch.
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 example of when to use it. It also notes that workflow nodes must be added separately via the UI/API, implying this tool is for initial creation only. However, it doesn't explicitly mention alternatives or when to use update vs create, so it's not a 5.
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?
Annotations already declare destructiveHint=true, but the description adds crucial context: confirmation is required and the token comes from a first call. This explains the two-step confirmation flow, which is beyond what annotations provide. However, it does not detail irreversibility or cascading effects on related resources.
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 and front-loaded with purpose and the destructive warning. The Args section is somewhat redundant with the schema but remains brief and organized. No filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and the presence of an output schema to cover return values, the description covers the essential aspects: action, destruction, confirmation, and parameters. It falls short of fully explaining the two-step confirmation procedure, but this is adequately implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains team_id as 'Team ID' (minimal) and confirmation_token as 'Token from first call' (useful and clarifies the flow). It adds some meaning but team_id lacks guidance on how to obtain it, and no details about the confirmation token's format or expiry.
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 immediately states 'Delete an AAP team' with a specific verb and resource, clearly distinguishing it from sibling tools like aap_delete_workflow_template or aap_delete_schedule. The meaning is unambiguous and directly matches the tool name.
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 when to use via 'DESTRUCTIVE - requires confirmation' but does not explicitly state when to choose this over alternatives or any exclusions. There is no mention of 'use this only for permanent removal' or comparison to update operations, leaving usage context mostly implicit.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by stating the return format (JSON string with status, elapsed time, and per-node results) and explicitly noting it covers running or completed jobs, which is useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary purpose, and uses a clear Args/Returns structure. Every sentence is useful, and there is no redundant elaboration.
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-only status tool with one parameter, the description covers what it does, what input it needs, and what output to expect. It lacks details like possible error conditions or status values, but given the existence of an output schema and strong annotations, this is adequate and mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats the parameter name and type ('workflow_job_id (int): Workflow job ID') without adding meaning beyond the schema. The schema itself provides a more informative description ('Workflow job ID (from launch response)'). Since schema description coverage is indicated as 0%, the description should compensate but does not.
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 status of a running or completed workflow job including node results. This is a specific verb+resource combination that distinguishes it from sibling tools like aap_get_job_output or aap_get_job_events.
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 checking workflow job status but does not provide explicit when-to-use vs alternatives or exclusions. The purpose sentence makes the use case understandable, but no guidance is given about when not to use it or what other tools to prefer for different scenarios.
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?
Annotations already mark readOnlyHint=false and destructiveHint=false, but the description adds a return format note (JSON with job id, status, monitoring tip), suggesting an asynchronous launch. However, it doesn't describe side effects, permission requirements, or that launching may trigger a job, leaving some 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an example, Args, and Returns sections. It is not overly verbose but includes some redundancy with schema descriptions and could be slightly tighter.
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 launch operation with a single nested params object, the description covers the action, all parameters, and return value. It lacks usage exclusions or prerequisites but is otherwise adequate for an agent to 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?
Although schema coverage is listed as 0%, the description's Args section explicitly explains workflow_id, extra_vars, and limit, adding meaning beyond the schema. It also indicates optionality for extra_vars and limit, though it does not specify the JSON/YAML format for extra_vars that the schema includes.
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 'Launch an AAP workflow template' with a concrete example, making the verb and resource explicit. This distinguishes it from sibling tools like aap_launch_job_template by specifying the workflow template 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?
The description implies usage when you want to launch a workflow template but provides no explicit guidance on when to prefer this over aap_launch_job_template or aap_relaunch_job. No when-not-to-use or alternatives are mentioned.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value beyond that by specifying the return format (JSON string with count and project list) and the exact fields per entry (id, name, scm_type, scm_url, status, last_updated), while also clarifying that projects are SCM-backed playbook repositories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a single front-loaded purpose sentence followed by concise Args and Returns blocks. Every sentence contributes information (purpose, input grouping, output format), with no fluff or 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?
Combined with the readOnly/destructive annotations and the existing output schema, the description covers purpose, parameter grouping, and return structure. It could be more explicit about pagination behavior (e.g., returns one page at a time vs. all projects), though the page/page_size parameters in the schema make this largely inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% at the top level, and the description only groups the params as 'Pagination and filter options' without detailing individual parameters. The schema itself provides descriptions for search and scm_type, but page and page_size lack explanations, and the tool description does not compensate for these 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 opens with 'List AAP projects (SCM-backed playbook repositories)', a specific verb+resource statement that clearly conveys the operation. The parenthetical adds scope by defining what an AAP project is, and the 'List' verb distinguishes this from sibling tools like aap_get_project, aap_create_project, aap_sync_project, and aap_delete_project.
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 usage is implied by the verb 'List' and the pagination/filter parameters, which suggest enumeration and browsing scenarios. However, there is no explicit guidance on when to use this versus aap_get_project for a single project or aap_list_organizations for other resources; no alternatives are named and no exclusion criteria 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?
Annotations already indicate a non-read-only, non-destructive operation. The description adds the PATCH method and return format, but does not disclose additional behavioral details like partial update semantics, error handling, or prerequisites. It adds some value but not rich 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?
The description is concise and well-structured with Args and Returns sections. Every sentence adds value and there is 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?
Given the low complexity and presence of an output schema, the description is adequate but has gaps. It lacks usage alternatives and does not mention that null values can clear fields. It covers the basics but could be more complete for an 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 description coverage is 0%, so the description must compensate. It lists 'Fields to update (name, description)' which clarifies the mutable fields, but does not explain the required 'team_id' parameter or its role as the identifier. This is partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update an existing AAP team (PATCH)'. It uses a specific verb and resource, and distinguishes it from sibling tools like create_team or delete_team.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by indicating 'existing team', which implies it is for updates, not creation. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds some context by specifying the return type ('Returns: str: YAML/JSON suitable for aap_configuration collection playbooks'), but does not disclose other behavioral details such as pagination, permissions, or format limitations. This is adequate given the annotations, 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 highly concise, with a clear one-line summary followed by structured Args and Returns sections. It contains only essential information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the existing annotations, and the presence of an output schema, the description is largely complete. It explains the purpose, parameters, and return format. However, it could have mentioned when to use this export variant instead of aap_export_all_resources or other export tools, which would add a little more context. The core information is all present, so it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The top-level schema parameter 'params' has no description (0% coverage), but the description's Args section compensates by listing project_id and format with their types and meanings. While the inner schema already contains these descriptions, the description clarifies the wrapper structure (ExportProjectInput) and makes the parameter purpose explicit, adding value beyond the schema alone.
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: 'Export an AAP project as Configuration-as-Code (infra.aap_configuration format).' This uses a specific verb ('Export'), identifies the resource ('AAP project'), and specifies the output format. It also distinguishes itself from sibling tools like aap_get_project (which fetches details) and other export tools for 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need to export a project in a configuration-as-code format, but it does not explicitly state when to use it over alternatives (e.g., aap_export_all_resources) or provide exclusions. The 'suitable for aap_configuration collection playbooks' phrase gives context but not direct usage 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it is an alias for activity stream with delete/create focus and mentions the return type, but since an output schema exists, the return type is redundant. No additional behavioral details like auth needs or rate limits are provided.
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, starting with a clear verb and resource, followed by a compact args/returns format. Every sentence adds value without any fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two parameters and an output schema, the description is largely complete. It explains the tool's purpose, parameters, and return type. However, the phrase 'delete/create focus' is slightly ambiguous and could be clarified, and there is no mention of pagination or any limits beyond the schema's constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself has minimal descriptions (username has a description, but limit does not), and the description compensates by explaining limit as 'Number of log entries' and username as 'Filter by actor'. This adds meaning beyond the schema, though the wording for username slightly differs from the schema's 'Filter by AAP username'.
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 AAP audit logs and specifies it as an alias for the activity stream with a delete/create focus. This specific verb+resource+scope distinguishes it from siblings like aap_get_recent_activity, making its 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for audit logs with a delete/create focus but does not explicitly state when to use this tool over alternatives such as aap_get_recent_activity or aap_get_failed_jobs. There is no mention of exclusions or alternative tools, only a vague contextual hint.
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 annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the 'ping endpoint' detail, which implies a lightweight network read operation, and lists the return fields. However, it does not disclose any additional behavioral traits such as authentication requirements, rate limits, or potential error conditions. Given the annotations, the bar is lower, and the description provides some supplementary context, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. It consists of one clear sentence plus a return specification, with no redundant or filler content. Every sentence earns its place by covering purpose and output.
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-only health check with no meaningful parameters and an existing output schema, the description is nearly complete. It states what the tool does and what it returns, which is sufficient for the agent to select and invoke it. It does not mention error handling or authentication, but these are likely common to all AAP tools and not critical for this simple endpoint.
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 one required 'params' field that is an empty object (HealthInput with no properties), meaning there are effectively no meaningful parameters. The description does not need to explain parameters, and the baseline for 0 parameters is 4. The description adds no parameter-specific information, which is fine because there is nothing to document.
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 ('Check') and clearly identifies the resource ('AAP Controller health status') plus the endpoint ('ping endpoint'). This effectively differentiates it from sibling tools like aap_get_cluster_status and aap_get_instance_capacity, which focus on different aspects of the system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking controller health but provides no explicit guidance on when to choose this tool over related alternatives such as aap_get_cluster_status or aap_get_instance_capacity. There are no 'when-to-use' or 'when-not-to-use' statements, so the agent must infer its context from the tool name.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with 'Get'. It adds value by listing what details are returned (credentials, labels, survey spec, etc.), which is not visible in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with clear Args and Returns sections. Every line adds value, and it is well-structured for quick parsing by an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, strong annotations, and a clear return description. The description covers the essential aspects of what the tool does and returns, making it complete enough 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?
The description repeats the schema's description 'Job template ID' for template_id, adding minimal new meaning. With the schema already providing the type and minimum, the description does not significantly compensate for the reported 0% schema coverage, but the parameter is simple and unambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full details of an AAP job template' with a specific verb and resource. It distinguishes from sibling tools like aap_list_job_templates by emphasizing 'full details' and listing the rich content returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you need full details of a job template. However, there is no explicit comparison to alternatives like aap_list_job_templates or aap_launch_job_template, nor any 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by explicitly enumerating the return fields (id, name, description, max_hosts, custom_virtualenv, created, modified), which goes beyond the annotations and clarifies what the output will contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with clear Args and Returns sections. The opening sentence states the purpose immediately, and every subsequent line serves a functional role. No filler or 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 single-parameter get operation, the description covers the purpose, the input parameter, and the return fields. While an explicit output schema is declared (context indicates one exists), it is not shown here; the description compensates by listing expected fields. The simplicity of the tool means this level of detail is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'org_id (int): Organization ID', which repeats the schema's type and label but adds no deeper semantic context such as how to obtain the ID or any relationships. The schema itself includes a description ('Organization ID (e.g., 1)'), so the tool description adds minimal informational value 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 opens with 'Get details of a specific AAP organization by ID', which uses a specific verb ('Get'), identifies the resource ('AAP organization'), and clarifies the scope ('by ID'). This clearly distinguishes it from siblings like aap_list_organizations (which returns a list) and aap_create/update/delete_organization (which mutate).
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 used when you already have an organization ID and need its details, but it does not explicitly state when to prefer this over aap_list_organizations or mention any exclusions. No alternatives or prerequisites are given, so guidance remains implicit rather than explicit.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read behavior is covered. The description adds the return format ('str: JSON with user list') and filtering capability, but does not disclose additional behavioral traits like rate limits, ordering, or pagination behavior beyond what the schema shows. 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?
The description is front-loaded with the main purpose, followed by an illustrative example and a clear Args/Returns breakdown. It is appropriately sized, with every sentence contributing useful information and 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 list tool, the description covers the essential operational details: what it does, key parameters, an example, and the return type. It lacks some context like default pagination values and whether results are ordered, but those are largely covered by the input schema, which specifies defaults and maximums. Overall, it is sufficiently complete for an agent to invoke the tool 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?
With schema description coverage at 0% per the context signals, the description compensates well by explicitly listing all parameters (page, page_size, search, is_superuser) with types and concise explanations. The example also clarifies how to use the is_superuser filter, adding practical meaning beyond the raw 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 'List AAP users' with a specific verb and resource. It includes an example ('List users with admin privileges') and distinguishes itself from sibling tools like aap_get_user, aap_create_user, aap_update_user, and aap_delete_user 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 provides an example of filtering for superusers, which implies when to use the filter. However, it does not explicitly compare this tool to alternatives (e.g., aap_get_user for a single user) or state when not to use it. The usage is implied but not fully specified.
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?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds some context by noting the return value includes a new job_id, implying a new job is created. However, it does not disclose side effects, permissions, or behavior for running jobs. With annotations present, the bar is lower, but the description could still be more transparent about mutation consequences.
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 a one-sentence purpose followed by structured Args and Returns sections. Every sentence is informative, and the format is easy to scan. No unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter, the description covers the purpose, parameters, and return value. It lacks details on error conditions or authentication, but these are not critical for a straightforward relaunch operation. The output schema existence also reduces the need to describe return structure in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's Args section repeats the schema descriptions for job_id and hosts, but adds a parenthetical '(retry only failed hosts)' for hosts, which clarifies the value 'failed'. The schema already had descriptions, so the description adds marginal value. Baseline of 3 is warranted.
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 'Relaunch' with the resource 'completed or failed AAP job', which is specific and distinguishes it from sibling tools like aap_launch_job_template (which launches new jobs from templates) and aap_cancel_job. The condition 'completed or failed' adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: for completed or failed jobs. It implicitly excludes running jobs, but it does not explicitly mention alternatives or when not to use it. This is clear context without exclusions, so a 4 is appropriate.
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?
Annotations already mark the tool as non-read-only and non-destructive. The description adds valuable context: only provided fields are modified, and it returns a JSON string with the updated template id and name. This goes beyond the annotations without contradiction.
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 short and well-structured: purpose, behavior, args, returns. Each sentence is necessary and information-dense with no 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?
The tool has one nested parameter with eight fields and no output schema, yet the description only vaguely refers to 'Fields to update' and gives a minimal return description. It explains partial update behavior and return value but leaves field semantics and requirements to be inferred from the schema, which has no descriptions. This is adequate for a simple update but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description should compensate by explaining fields. It only says 'Fields to update', which repeats the schema's existence without adding meaning. Field names are somewhat self-explanatory, but the description itself adds no 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 states 'Update an existing AAP job template (PATCH)' with a specific verb and resource, and the PATCH method clarifies partial modification. This clearly distinguishes it from sibling tools like create, delete, launch, and copy job templates.
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?
'Only fields provided will be changed' provides clear context for partial updates, implying it is for modifying existing templates without replacement. However, no explicit alternatives or when-not-to-use guidance is mentioned, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds the important behavioral detail that confirmation is required, with a token from the first call needed for the second call. This goes beyond the annotation by explaining the confirmation mechanism, though it doesn't specify what the first call returns beyond the implied token.
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 brief and well-structured: a single sentence stating purpose and warning, followed by a concise parameter list. No unnecessary words or repetition.
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 a destructive two-step confirmation flow, and the description does explain the token requirement, which is crucial. However, it doesn't describe the behavior of the first call in detail (e.g., whether it returns a token or queues the deletion), nor any error conditions. An output schema exists, so return values are not required, but the workflow is still somewhat underspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists both parameters with brief explanations: group_id as 'Group ID' (minimal, tautological) and confirmation_token as 'Token from first call' (adds meaningful context about the workflow). This is helpful but lacks depth, such as how to obtain the token or what values are valid.
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 'Delete a host group from an AAP inventory' clearly states the specific action (delete), resource (host group), and system (AAP inventory). This distinguishes it from sibling tools like aap_remove_host_from_group, which removes a host rather than deleting the group itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting the destructive nature and the confirmation requirement, which implies a two-step usage process. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions, though the purpose is specific enough that alternatives are obvious.
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?
Beyond the readOnlyHint annotation, the description discloses that secrets are masked by AAP and appear as '$encrypted$', and that the return is a JSON string. This provides meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with a clear intro and structured Args/Returns sections. Every sentence contributes to understanding the tool's behavior without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read operation, the description adequately covers the return format and secret-masking behavior. It doesn't discuss error cases or ID validation, but given the simplicity and read-only nature, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description merely restates the parameter name and type from the schema ('credential_id (int): Credential ID'), adding no new semantic meaning. With schema description coverage at 0%, it fails to compensate by explaining the parameter's role or 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 uses a specific verb ('Get') and resource ('credential details') with an added detail about secret masking, clearly distinguishing it from sibling list/delete/update tools. It unambiguously states the operation's scope (fetching a single credential).
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 fetching individual credential details but provides no explicit guidance on when to use it compared to alternatives like aap_list_credentials. No exclusions or when-not-to-use scenarios are mentioned.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that it returns 'JSON with capacity, consumed capacity, running jobs.' This provides useful behavioral context about the return value without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and uses a clean Args/Returns structure. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and an output schema present, the description covers the target and the return contents (capacity, consumed capacity, running jobs). It lacks details on error conditions or prerequisites, but these are not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero meaningful description coverage; the description simply repeats 'Instance ID' without adding semantics. It does not explain how to identify the node or any relationships to other resources, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get capacity and workload details for a specific AAP controller node,' clearly specifying the action (get), the resource (capacity/workload details), and the scope (a specific node). This distinguishes it from siblings like 'aap_list_instances' or 'aap_get_cluster_status'.
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 a specific node's capacity details, which is clear context. However, it does not explicitly mention alternatives or when not to use this tool (e.g., for cluster-level capacity). Slight gap in exclusions.
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?
Annotations already mark the tool as readOnly and non-destructive. The description adds valuable behavioral context by disclosing that the return is JSON with status, elapsed time, and output preview, which goes beyond the annotations alone. No contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for purpose, arguments, and return value. Each part earns its place, with no unnecessary 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?
Given the tool's simplicity (one parameter, read-only, with annotations and an output schema), the description is nearly complete. It covers purpose and return format, though it could explicitly mention that the update_id comes from a prior sync_project call. However, the schema description fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's argument list merely restates the parameter name and type ('update_id (int): Project update ID') without explaining what the update ID refers to or where to obtain it. The schema's own description ('Project update ID from sync_project response') is actually more informative, so the description adds little value beyond the structured 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 the status of a project SCM sync, using the specific verb 'Get' and the resource 'project SCM sync'. It is distinct from sibling tools like aap_get_project or aap_get_workflow_status, which target other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is used to check the status of a project sync, whether ongoing or completed. While it does not explicitly name alternatives or exclusions, the context of 'project SCM sync' and the sibling aap_sync_project make the usage context 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 discloses the return behavior: 'JSON with job id, status, url, and monitoring instructions.' Annotations already indicate a non-read-only, non-idempotent, non-destructive operation, so the description adds value by explaining what the agent can expect in the response. No contradiction 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear one-sentence purpose, followed by two illustrative examples and then an organized Args/Returns listing. It's not overly verbose, though the Args list partly duplicates the schema. The structure makes it easy to scan.
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 primary purpose, all key parameters (except credential_id), and return value format. It includes examples and monitoring guidance, which is useful for follow-up actions. However, it lacks mention of prerequisites (e.g., template must exist) or failure scenarios, and the first example uses the word 'workflow' which could be confused with the sibling aap_launch_workflow tool. Overall, sufficiently complete for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptive comments for all parameters (e.g., 'Ansible tags to run (comma-separated)'), so the baseline is 3. The description repeats most parameters but omits 'credential_id' and offers no additional meaning beyond what the schema gives, except for noting 'Override inventory' and 'Show diffs' which mirror 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 action ('Launch an AAP job template') and the resource ('job template'), distinguishing it from sibling tools like aap_launch_workflow for workflows. The examples further clarify real-world usage. This is a specific, unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when a user requests launching a job template. It does not explicitly name alternative tools or say when NOT to use it, but the tool name and description make it obvious. Examples of natural-language triggers give additional 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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by disclosing the return format (JSON with id, name, kind, injectors schema) and the managed filter behavior, which go beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a one-sentence purpose, a usage hint, a bullet for arguments, and a return line. Every line earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with read-only annotations and a clear output description, the tool is mostly complete. It includes the key return fields and a usage tie-in, but could mention pagination parameters for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% at the top level. The description only explains the 'managed' parameter but omits mention of 'page' and 'page_size' entirely. This leaves most of the input object undocumented, so the description does not fully compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List available AAP credential types' with concrete examples (SSH, Vault, AWS, Azure). It differentiates from sibling tools by explicitly noting the returned id is used for aap_create_credential, and the name aap_list_credential_types contrasts with aap_list_credentials.
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 clear usage context: use this tool to fetch credential type IDs for creating credentials. It does not explicitly mention alternatives or exclusions, but the purpose is specific enough to avoid confusion with the many sibling 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?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds that it returns a JSON confirmation, which is useful, but does not disclose side effects, idempotency, or prerequisite conditions. Given the annotations, this is acceptable but not richly detailed.
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, front-loaded with the main purpose, and includes clearly structured Args and Returns sections. No unnecessary words or redundant 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 two-parameter tool, the description is complete enough. It states the action, parameters, and return type. It doesn't cover edge cases or permissions, but the complexity is low and annotations provide basic safety hints. The output schema presence (indicated by context) reduces the need to explain return values in detail.
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 no descriptions for parameters, only titles and minimums. The description compensates by explaining team_id as 'Team ID' and user_id as 'User ID to add,' clarifying the latter's role. This adds meaning beyond the schema, though it could be more expansive.
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: 'Add a user to an AAP team.' It uses a specific verb and resource, and the name also aligns. Among sibling tools like aap_remove_user_from_team, the purpose is 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 clearly implies usage: when you need to add a user to a team. It doesn't explicitly mention alternatives or when-not-to-use, but the context of sibling tools makes the appropriate scenario evident. No exclusions are stated, so it's not a 5.
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?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses a two-step confirmation flow: the first call returns a confirmation prompt, and a second call with a token returns success. This adds meaningful behavioral context not present in the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Args and Returns sections. It includes only necessary information and is immediately scannable, with 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?
With a simple tool and an output schema (str), the description covers purpose, confirmation workflow, parameters, and return type. It lacks edge-case details like error handling or prerequisites, but these are not critical for this operation and the description is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a basic description for job_id and none for confirmation_token. The description explains the confirmation token's purpose ('Token from first call') and ties the parameters into the workflow, significantly aiding parameter understanding beyond what the schema offers.
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 ('Cancel a running AAP job') with a specific verb and resource, distinguishing it from sibling tools like launch or relaunch. The phrase 'Requires confirmation' adds an important extra layer of specificity.
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 cancelling running jobs) but does not explicitly mention alternatives like relaunch or conditions when not to use. The guidance is minimal, relying on the tool name and context rather than explicit instructions.
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?
Beyond the destructiveHint=true annotation, the description explicitly warns 'DESTRUCTIVE - requires confirmation' and explains confirmation_token as 'Token from first call', disclosing the two-step confirmation flow. This adds meaningful behavioral context that annotations alone do not convey, though it omits details like error handling or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the action and a clear warning. The Args section is straightforward and every sentence serves a purpose. No unnecessary words or redundancy with the schema.
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 and the presence of an output schema, the description covers the essential operation and the confirmation flow. It does not discuss prerequisites, behavior when confirmation_token is omitted, or the distinction from similar delete tools, but these are not critical for a basic delete operation. The warning and token explanation make it adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for the parameters, but the description lists both host_id and confirmation_token. Crucially, it explains confirmation_token as 'Token from first call', which clarifies the two-step confirmation mechanism. host_id is only given a generic 'Host ID' label, which is thin, but the token semantics significantly enhance 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 and resource: 'Delete a host from an AAP inventory.' This clearly distinguishes it from sibling tools like aap_remove_host_from_group, which removes host-group membership rather than deleting the host.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (deleting a host) but provides no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. For example, it does not clarify when to use aap_delete_host vs aap_remove_host_from_group. 'Requires confirmation' hints at a two-step flow but gives no strategic 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?
Annotations already mark destructiveHint=true, and the description reinforces it with 'DESTRUCTIVE - requires confirmation.' It goes beyond annotations by explaining the confirmation token flow and the return behavior (confirmation prompt or success JSON). No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured with Args and Returns sections. Every sentence adds value; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully explains the delete operation, including the required confirmation step and the return format. The output schema is present, so return details are not needed. The tool is simple enough that this description is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description explicitly lists both parameters and their meanings. It adds the crucial detail that confirmation_token is the token from the first call, which is essential for the two-step flow. project_id is described as 'Project ID,' which is minimal but clear.
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 states 'Delete an AAP project' — a specific verb and resource. It doesn't explicitly distinguish from sibling delete tools, but the resource is clear from the name and description. The confirmation note adds specificity.
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 doesn't explicitly say when to use this tool vs alternatives, but it clearly communicates the two-step confirmation process: first call returns a prompt, and the token from that call must be passed to confirm deletion. This provides context on how to use it correctly. No exclusions or alternatives are mentioned.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value by specifying the return type (str of YAML) and its compatibility with a specific collection, which goes beyond the annotations. It doesn't mention potential permissions or rate limits, but for a read-only export tool this is not a major omission.
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, using Args/Returns format. The key purpose (export job template as YAML) is front-loaded, and every line adds useful information without redundancy. It fits the information in a compact, readable form.
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 relatively simple tool with two parameters and no nested objects, the description plus schema and annotations provide enough context to invoke it correctly. The return type is specified, and the compatibility note helps set expectations. The lack of explicit usage guidance prevents a 5, but overall the information is adequate for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly lists both parameters (template_id and format) with their expected types and values, which aligns with the schema. It adds a bit of context by indicating the format choices ('yaml' or 'json') and the return compatibility. However, it does not mention the default value of format, which is present in the schema. The parameter coverage in the description is good, though not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (export), the resource (job template), and the output format (Configuration-as-Code YAML). It distinguishes itself from sibling tools like aap_get_job_template by focusing on export-to-code, and from other export tools by targeting job templates specifically.
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 Infrastructure-as-Code workflows via the 'Configuration-as-Code' phrase and compatibility with infra.aap_configuration, but it does not explicitly state when to choose this tool over alternatives like aap_export_all_resources or aap_get_job_template. No exclusions or alternative guidance are 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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the returned fields (id, name, started, finished, elapsed, template name) and the filtering parameters, which enriches the behavioral understanding beyond the annotations. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-line purpose, an example, a structured Args section, and a Returns section. Every sentence contributes useful information without extraneous text.
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-only list tool with an output schema, the description covers purpose, parameters, and return format. It lacks explicit guidance on pagination or alternative tool selection, but it is sufficiently complete for an agent to 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?
Although the schema has descriptions for each parameter, the context signal indicates 0% schema description coverage, so the description's explicit listing of hours, limit, and job_template with meanings and defaults compensates effectively. It clarifies the look-back window, result limit, and optional template filter, though it omits min/max bounds (present 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 starts with a specific verb ('List') and resource ('failed AAP jobs') and adds a time window scope ('within the last N hours'). This distinguishes it from sibling tools like aap_list_running_jobs and aap_get_job_output, making its 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an example ('Show failed jobs from the last 24 hours') and details the hour/limit/template parameters, implying it is for listing recent failed jobs. However, it does not explicitly state when to use this tool instead of alternatives like listing running jobs or querying job output, nor does it mention any exclusions.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral detail beyond that: it mentions output truncation ('truncated output'), format options ('txt' or 'json'), and the inclusion of 'status' in JSON mode. This gives the agent a clearer picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, a one-sentence use case, a clear args list, and a returns statement. Every part contributes value and there is no filler. The front-loaded purpose makes it easy to scan.
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-only output fetcher, the description covers the core aspects: what it does, when to use it, the parameters, and the return format. Minor gaps exist around error scenarios (e.g., job not found, format of JSON status), but annotations and output-schema presence (which we don't see explicitly) reduce the need for more detail.
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 complete descriptions for all three parameters (job_id, format, max_lines), so the description does not add significant new semantics. It restates defaults like 'default 200' which are in the schema. The description is helpful for quick reference, but it is largely redundant with schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource combination: 'Fetch stdout/stderr output from an AAP job run.' This clearly states the tool's function and differentiates it from sibling tools like aap_get_job_events or aap_list_running_jobs. The additional 'Useful for troubleshooting failures' reinforces its intent without ambiguity.
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 context for use ('Useful for troubleshooting failures or reviewing what a job did'), indicating when an agent should choose this tool. It does not explicitly mention alternatives or when not to use it, but the purpose statement is strong enough to guide selection 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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context by stating the return format ('JSON with workflow details and node count') and emphasizes the node structure, which goes beyond the annotations. No contradictions found.
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: one main sentence followed by Args and Returns sections. Every sentence provides necessary information, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read operation with one parameter and an output schema. The description covers the key details: it returns full details including node structure, and the schema already documents the return type. No significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% because the description's parameter line ('workflow_id (int): Workflow template ID') exactly repeats the schema property description. It adds no new meaning, and with only one parameter the description could have added context (e.g., where to find the ID, or that it must be an existing template).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full details of an AAP workflow template including node structure,' which specifies the verb (get), the resource (workflow template), and a distinguishing detail (node structure). This differentiates it from list operations like aap_list_workflow_templates.
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: it is for retrieving full details of a single workflow template. However, it does not explicitly mention alternatives or when not to use it, so it earns a 4 rather than 5.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral detail: the return type (JSON string) and the specific fields included in each result, which goes beyond the structured annotations.
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 structured docstring with Args and Returns sections is well-organized and easy to scan. While it repeats parameter information, every sentence serves a purpose and there is no fluff. Slightly longer than necessary but still concise.
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 listing action, optional filters, and return structure in sufficient detail for a read-only list tool. It does not mention ordering or pagination behavior beyond the page/page_size parameters, but these are already in the schema. The presence of an output schema also lessens the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly lists all five parameters with types and meaning, including page/page_size which the schema describes only with types/defaults. Given the schema's 0% coverage at the top level, the description fully compensates and even clarifies filtering 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 opens with 'List AAP job templates with optional filtering,' using the specific verb 'List' and naming the resource 'AAP job templates.' This clearly distinguishes it from siblings like aap_get_job_template (retrieve single) and aap_create_job_template.
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 through 'with optional filtering' and the parameter list, but it does not explicitly state when to prefer this tool over alternatives such as aap_get_job_template for a single template or aap_launch_job_template for execution. There is no when-not 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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the specific behavioral nuance that the host is not deleted but merely disassociated, which is useful. However, it does not mention permissions, idempotency, or error behavior, leaving some transparency 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 succinct and well-structured: a one-sentence purpose, a params list, and a returns line. Every sentence earns its place with no redundancy or unnecessary elaboration.
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 removal operation, the description covers the core aspects: what it does (disassociate), the parameters, and the return value. The distinction from delete_host is clear, and sibling tool names provide context. It lacks only minor details like prerequisites (e.g., host must be in group), but the description is adequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the 'Args' section in the description provides essential semantics: group_id is 'Group ID' and host_id is 'Host ID to remove'. This compensates for the schema's lack of descriptions, though it does not mention the minimum=1 constraints which are 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: 'Remove a host from a group', specifying the verb, resource, and scope. It also distinguishes from sibling tools like 'delete_host' via the parenthetical 'disassociate, not delete the host', 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 explicitly notes 'disassociate, not delete the host', which serves as a when-not guideline and distinguishes from alternative deletion operations. However, it does not explicitly name alternative tools like aap_delete_host or aap_add_host_to_group, so it lacks the full explicit 'use X instead' structure.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read. The description adds useful context about the return shape (JSON with license type, expiry, host count, validity status), which goes beyond the basic safety profile.
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 gives the purpose, the second summarizes the return value. No filler, front-loaded, and easy 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—no parameters, no side effects, read-only—and the presence of annotations and an output schema, the description is complete. It provides enough context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required 'params' object with no properties, effectively zero meaningful parameters. The baseline for 0 params is 4; the description adds no parameter details but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get AAP subscription and license details', which is a specific verb and resource. It distinguishes the tool from all siblings, none of which handle license info.
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 usage is implied—when you need license details—but there is no explicit guidance on when to use this vs alternatives, or exclusions. Sibling tools cover different resources, so it is somewhat clear but not explicitly 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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value by stating that the tool supports pagination and filter options, and by detailing the return fields (id, name, inventory, enabled, variables). This goes beyond the annotations, though it does not mention any specific permissions or rate-limit behavior, which is acceptable for a read-only 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?
The description is extremely concise and well-structured with clear sections for Args and Returns. Every sentence adds value, avoiding redundancy with the schema or annotations. It is front-loaded with the core purpose in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with rich annotations (readOnlyHint, destructiveHint) and an output schema, the description provides sufficient context: it names the resource, the operation, the parameter purpose, and the return structure. No additional behavioral or prerequisite information is necessary for this straightforward use case.
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 description coverage is 0%, so the description must compensate. It provides a high-level summary: 'params (ListHostsInput): Pagination and filter options,' which adds context beyond the raw schema. However, it does not detail individual parameters or their filters; it relies on the schema's own descriptions for some fields (search, enabled, inventory_id). This is a modest contribution, not full compensation.
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 and resource: 'List hosts in an AAP inventory.' It clearly distinguishes from sibling tools like create_host, update_host, and delete_host, and aligns with the tool name. It also specifies the return content (id, name, inventory, enabled, variables), 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 clear context that this tool lists hosts within an inventory, implicitly indicating when to use it (when a host listing is needed). It does not explicitly mention alternatives or exclusions, but no conflicting sibling tools exist for listing hosts, so the context is sufficient. A minor deduction for not explicitly stating scenarios like 'use when you need to see hosts in an inventory'.
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?
Annotations already declare destructiveHint=true, but the description adds the confirmation token mechanism and the dual return states (confirmation prompt vs success JSON). This goes beyond the annotations and gives the agent actionable behavioral details. 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?
The description is extremely concise and well-structured: a one-line purpose, then args, then returns. Every sentence earns its place, and the dangerous nature is front-loaded with 'DESTRUCTIVE - requires confirmation.'
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 two-step confirmation flow is adequately explained, and the output is just a string so no detailed return schema is needed. It is complete enough for an agent to understand the tool's behavior, though it omits potential error cases or prerequisites beyond confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It explains both parameters: credential_id as the target ID and confirmation_token as the token from the first call. This adds meaning beyond the raw schema types, though it could be slightly more detailed about how the token is obtained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete an AAP credential', which is a specific verb + resource that clearly distinguishes this from sibling delete tools for other resources. The 'DESTRUCTIVE' warning adds important scope clarification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context about the two-step confirmation flow ('requires confirmation', 'Token from first call') and return behavior. However, it does not explicitly name alternatives or state when not to use this tool, though the purpose is self-evident from the resource type.
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?
Annotations already mark the tool as destructive, and the description adds the crucial detail that confirmation is required, along with the confirmation token flow. This goes beyond the annotation by explaining the interactive confirmation mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear 'Args' and 'Returns' sections. Every sentence provides useful information without unnecessary fluff, making it easy to scan.
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 destructive nature and confirmation flow, the description covers the essential steps and return types. It doesn't mention side effects beyond deletion, but the annotation and confirmation details make it sufficiently complete for an 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?
The input schema has no description coverage for parameters, but the description explains that workflow_id is the template ID and confirmation_token comes from the first call. This adds essential semantics beyond the raw schema fields.
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 'Delete an AAP workflow template', clearly stating the action (delete) and target resource (workflow template). This is specific and distinguishes it from sibling delete tools targeting other resources.
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 indicates the two-step confirmation process ('requires confirmation') and the token parameter, giving clear context on how the tool should be used. However, it does not explicitly name alternatives or state when not to use this tool, which prevents a 5.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the output being YAML for infra.aap_configuration.controller_inventories and clarifies the format parameter allows 'yaml' or 'json', exceeding mere annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and uses a structured Args/Returns format. Every sentence adds value without redundancy, and the entire description is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only export tool with annotations and an output schema, the description covers purpose, parameters, and return format sufficiently. It does not need additional side-effect or error-handling details, making it complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's Args section provides meaningful explanations for all three parameters (inventory_id, include_hosts, format), including allowed values for format. This compensates for the schema's low description coverage and adds clarity beyond the basic types 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 tool exports an AAP inventory as Configuration-as-Code YAML, specifying the action, resource, and output format. It is distinct from sibling export tools (e.g., aap_export_project) by explicitly naming the inventory as the target 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?
The description implies usage for exporting inventories but does not explicitly discuss when to use this tool versus alternatives like aap_export_all_resources or other export tools. There is no exclusion guidance, so it is clear but not fully 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?
With readOnlyHint=true and destructiveHint=false annotations, the safety profile is already disclosed. The description adds that the output is a string in YAML/JSON format and that it is Configuration-as-Code compatible, providing useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The docstring is compact, structured with Args and Returns, and contains no fluff. Each sentence serves a purpose.
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-only export tool, the description covers purpose, parameters, and return format. It doesn't mention error cases or prerequisites, but with readOnly annotations and an output schema, this is sufficient. Sibling export tools have similar level of info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions (0% coverage), so the description compensates by defining workflow_id as 'Workflow template ID' and format as either 'yaml' or 'json', clarifying the string format and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Export a workflow template as Configuration-as-Code YAML.' This clearly differentiates from sibling export tools (e.g., export_project, export_job_template) by naming the resource type and output format.
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 workflow template exports and specifies the output is compatible with infra.aap_configuration.controller_workflows. It does not explicitly describe when to choose this over export_all_resources or sibling export tools, but the resource-specific purpose 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining the paginated response format and return keys (count, page, page_size, results), which goes beyond annotation data. It does not disclose potential edge cases like empty results, but for a simple read-only list 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by return details and parameter summary. It is slightly longer than necessary because the Args section repeats schema information, but it remains well-structured and readable without being verbose.
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 (a read-only list with pagination), the description covers everything needed: what it does, what it returns, and how parameters affect the result. The presence of an output schema (or the inline return description) and strong annotations complete the picture, leaving no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that explicitly lists each parameter with its default and purpose (page, page_size, search), which is redundant with the schema but still helpful. Even though schema coverage is reported as 0%, the description fully compensates by documenting all three sub-parameters clearly.
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 'List all organizations in Ansible Automation Platform', using a specific verb ('List') and resource ('organizations') with clear scope. It also states what the response contains (IDs, names, descriptions, member counts), distinguishing it from the sibling 'aap_get_organization' which retrieves a single organization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool lists all organizations and supports pagination, implying its use for bulk retrieval. It does not explicitly name alternatives like 'aap_get_organization' for single-org lookups, so it lacks an explicit when-not-to-use statement, but the context is clear enough for an agent to choose correctly.
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?
Annotations already mark this as read-only and non-destructive. The description adds the scope 'all currently running jobs' and specifies the return type as a JSON string, which adds context beyond the annotations. It does not contradict the read-only hint.
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 lines plus a compact docstring, front-loaded with the action. It uses no filler and each sentence serves a purpose.
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 single-parameter read-only list operation, the description covers the action, the parameter, and the return format. With annotations and an output schema present, this is sufficient context for an agent.
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 0%, but the description explicitly documents the sole parameter include_workflow_jobs ('Also show running workflow jobs'), giving it meaning beyond the raw boolean type and default 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 opens with 'List all currently running jobs in AAP', a specific verb and resource. It clearly distinguishes itself from sibling tools like aap_cancel_job and aap_get_job_output by focusing on listing running jobs.
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 retrieving running jobs but does not mention alternative tools or when not to use it. No explicit contrast with sibling tools such as aap_get_failed_jobs or aap_get_recent_activity 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?
Annotations already indicate it is mutating, idempotent, and non-destructive. The description adds PATCH semantics (only provided fields updated) and return format, which is valuable contextual information beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, front-loading the purpose, then stating PATCH behavior, followed by an args list and return value. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, parameters, and return value. Annotations provide safety context. It lacks explicit mention of permissions or error conditions, but for a non-destructive, idempotent update tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's Args section explains each parameter (org_id, name, description, max_hosts) with meaningful semantics. This compensates for the schema's lack of 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 'Update an existing AAP organization,' with a specific verb and resource. It distinguishes from sibling tools like create/delete/get/list organizations.
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 clearly implies usage when modifying an existing organization and explains PATCH semantics, but does not explicitly mention alternatives or exclusions. The context is clear, so it earns a 4.
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?
Annotations already indicate a write operation (readOnlyHint=false) and not destructive. The description adds the return format (JSON with id and name) and the dependency on credential type lookup. It discloses essential behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose in the first sentence, then the prerequisite tip, and then structured Args/Returns. It is compact and each sentence serves a purpose, with no unnecessary elaboration.
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, the description covers the necessary context: what to do first (list types), what parameters are needed, and what the return value is. It doesn't cover error handling, but that's not critical for a create 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?
Despite schema description coverage of 0%, the description details every parameter in the Args section with types and brief meanings, e.g., 'inputs (dict): Type-specific inputs (username, password, ssh_key_data, etc.)'. It adds examples and clarifies optionality, providing strong semantic value 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 'Create a new AAP credential' with a specific verb and resource, and the tool name reinforces this. It differentiates from sibling tools like aap_update_credential and aap_delete_credential by using 'Create' and providing creation-specific guidance.
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 instructs to use aap_list_credential_types first to find the correct type ID and understand required inputs, which is a clear prerequisite and contextual alternative. It doesn't explicitly mention when not to use the tool, but the verb 'Create' implies this is for creation only, making it distinct from update/delete 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?
Beyond the annotations (destructiveHint=true), the description discloses the two-step confirmation mechanism: the first call returns a prompt, and the second call with a confirmation_token performs deletion. It also specifies the return type (confirmation prompt or success JSON). This adds substantial 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with a clear one-sentence summary followed by structured Args and Returns sections. No unnecessary words; every line is functional.
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?
The description fully covers the tool's purpose, destructive nature, confirmation workflow, parameters, and return type. Given the simple schema and the presence of destructiveHint annotation, this is complete and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists parameters from the schema but adds minimal new meaning. It clarifies inventory_id is an 'Inventory ID' (redundant) and describes confirmation_token as 'Token from first call,' which is useful but modest. Schema coverage is 0%, so the description partially compensates.
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 'Delete an AAP inventory,' which is a specific verb+resource statement. It clearly distinguishes this tool from sibling delete tools for other AAP resources (e.g., delete_host, delete_workflow_template).
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 warns 'DESTRUCTIVE - requires confirmation,' providing clear context that the caller must handle a confirmation flow. It doesn't state alternatives, but for a delete operation the intent is unambiguous and no exclusion is needed.
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?
The annotations already declare destructiveHint=true, but the description adds critical behavioral detail beyond that: the tool does not delete on the first call—it returns a confirmation prompt, and the confirmation_token from that call is required to complete the deletion. This two-step protocol is essential for an agent to invoke the tool correctly and is not inferable from annotations or schema. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, leading with the purpose and a DESTRUCTIVE warning before structured Args and Returns sections. Every sentence serves operational value—no filler or redundant annotation repetition. The docstring format is clean 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?
Given the tool's complex two-call destructive flow and zero parameter descriptions in the schema, the description covers the full lifecycle: first call yields a confirmation prompt, second call with token yields success JSON. Minor gaps remain around failure modes (e.g., invalid confirmation_token) and side effects on dependent resources like schedules, but the core operational behavior is adequately specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining both parameters: 'template_id (int): Template ID to delete' and 'confirmation_token (Optional[str]): Token from first call.' The token description links it meaningfully to the confirmation flow, adding semantics far beyond the bare schema types 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 opens with 'Delete an AAP job template,' a specific verb+resource statement that unambiguously identifies the tool's function. This clearly distinguishes it from sibling tools like aap_delete_workflow_template, aap_delete_schedule, and aap_delete_organization, which target different resources. The DESTRUCTIVE warning reinforces the purpose.
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 context via 'DESTRUCTIVE - requires confirmation' and outlines the two-call token flow, implying when it is safe to use (after confirmation). However, it does not explicitly name alternatives or exclusion criteria relative to siblings like aap_update_job_template or aap_launch_job_template. Usage guidance is implied rather than explicitly contrasted.
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?
Annotations already establish readOnly=true and destructive=false. The description adds the concrete behavioral detail that output is 'a single YAML document compatible with the infra.aap_configuration Ansible collection' and that it returns a 'Combined YAML/JSON export' as a string, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary line, example, output note, and Args section. Every part provides useful information without unnecessary fluff, and it remains within a reasonable length.
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 purpose, usage, parameters, and return type, which is sufficient for this read-only export tool given annotations. It does not mention potential size limits or authentication requirements, but these are not essential given the tool's simple contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents both parameters in an Args section, adding meaning to the bare schema: organization_id 'scopes exports to one org' and format is restricted to 'yaml' or 'json'. The schema only provides a terse note on organization_id and no description for format, so this is significant added 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 explicitly states the verb 'Export' and the exact resource scope: 'all AAP resources (projects, inventories, job templates, workflows)'. It also distinguishes from sibling export tools by emphasizing 'all' resources, and includes an example.
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 use case via the example 'Export all job templates as code' and clarifies the bulk export scope. However, it does not explicitly mention when to use this tool over the individual export siblings (e.g., aap_export_project), so it lacks explicit exclusions.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds substantive context about granularity, per-host task results, and the JSON return format, which enriches the behavioral understanding beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, with a leading purpose sentence, a useful comparison, and clearly separated Args/Returns sections. Every line contributes value, and there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only event listing tool with annotations, an output schema, and a sibling tool, the description adequately covers purpose, usage context, parameters, and return format. It provides enough information for an agent to select and invoke it correctly without major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly enumerates the parameters and gives one-line meanings (job_id, event_type filter, pagination), compensating for the 0% schema description coverage at the top level. While the nested schema already documents job_id and event_type with descriptions, the description ensures all parameters are understandable without deep schema inspection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'Get' and identifies a concrete resource: structured events from an AAP job (tasks, roles, failures). It explicitly differentiates from stdout output, which directly addresses the sibling tool aap_get_job_output. This makes 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?
'More granular than stdout - shows individual task results per host' provides clear context for when to choose this tool over a raw stdout viewer. It does not explicitly name the alternative tool or state exclusions, but the comparison is strong enough for an agent to infer the right use case.
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?
The description discloses the critical two-step confirmation process, which goes beyond the annotations (destructiveHint=true). It explains that the first call returns a token and the second call performs the deletion, adding meaningful behavioral context. It also mentions the return types (confirmation request message or success/error JSON), giving a complete picture of the tool's 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 compact and well-organized, using clear sections for the action, the two-step process, parameters, and return value. No redundant or filler content appears. Every sentence contributes to understanding the tool, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is destructive and requires a multi-call workflow, and the description captures all essential aspects: the action, the confirmation mechanism, the parameters with their roles, and the expected output. The presence of an output schema is not required because the return behavior is explicitly described. The description is complete for an agent to safely invoke the 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?
Although the input schema includes property descriptions for org_id and confirmation_token, the description enhances them by explaining the relationship between the two parameters: the token is issued by the first call and required to execute the deletion. This sequencing information is not fully captured in the schema and adds clear 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 opens with 'Delete an AAP organization' – a specific verb, resource, and clear scope. It clearly distinguishes this from sibling delete tools (e.g., aap_delete_user, aap_delete_team) by naming the exact resource type. The destructive nature is emphasized with 'DESTRUCTIVE', further clarifying the tool's 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?
The description provides explicit step-by-step usage: first call without the confirmation token to obtain one, then call again with the token to confirm deletion. This outlines the required sequence and the purpose of each call. It does not, however, discuss alternatives or when not to use the tool, so it misses the full 'when-not' guidance.
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:

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

Score Badge

Copy to your README.md:

[![aap-mcp-server MCP server](https://glama.ai/mcp/servers/srinivassrinu842/aap-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/srinivassrinu842/aap-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/srinivassrinu842/aap-mcp-server'

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