DoiT MCP Server

Official

by doitintl

Overview Schema Related Servers Score Discussions(1)

TypeScript

Remote

Server Quality Checklist

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

Latest release: v1.0.1
Disambiguation4/5
The server uses extensive 'Do NOT use this for X' cross-references to disambiguate tools, which is very helpful. Most tools have distinct purposes and clear resource-action targets. However, a few tools like id_of_asset (which actually updates an asset) and the overlap between run_query, cost_breakdown, cost_trend, and compare_spend could cause occasional misselection, though their descriptions mitigate this.
Naming Consistency3/5
The naming mostly follows the verb_noun pattern (list_, get_, create_, update_, delete_), but there are notable inconsistencies: 'id_of_asset' is an odd name for an update operation, 'datahub_events_csv_file' is not verb-first, and there are plural/singular mismatches like 'get_cloud_diagrams_stats' vs 'get_cloud_diagram_cost_snapshot'. These deviations break a clean pattern.
Tool Count1/5
With 166 tools, this server is vastly over-scoped for an MCP toolset. Agents would face extreme selection complexity. The calibration guidelines state that 50+ tools is an extreme mismatch, and this exceeds that by far. The tool count alone makes the server unwieldy and difficult to navigate, even if individual tools are well-described.
Completeness4/5
The toolset covers an impressively broad range of DoiT domains including cost analytics, budgets, alerts, labels, folders, themes, users, tickets, CloudFlow, DataHub, insights, cloud diagrams, and AWS commitments. Most resources have full CRUD or appropriate lifecycle coverage. Minor gaps exist (e.g., no delete_asset, no create_role), but overall the surface is quite complete for the stated purposes.
Average 4/5 across 159 of 166 tools scored. Lowest: 1.7/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 100 commits in the last 12 weeks
- Last stable release on September 4, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is misleading by starting with 'Ingest...' which conflicts with the delete action. Annotations correctly mark destructiveHint: true, but the description adds confusion instead of clarity. No mention of consequences (e.g., irreversible deletion) beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, but the first sentence is irrelevant and misleading. The structure is not concise because it includes unnecessary information (ingestion) that harms clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is destructive, has no output schema, and one parameter lacks description, the description is critically incomplete. It fails to mention that deletion is permanent, error conditions, or any required preconditions.
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 50% (only customerContext has a description). The tool description does not explain the 'name' parameter at all, leaving ambiguity about what name refers to (dataset ID? name string?). The description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Ingest third-party cost...' which suggests a create/ingest action, then contradicts with 'Deletes a specific DataHub dataset.' The purpose is vague and inconsistent, and it does not distinguish from sibling tools like 'delete_datahub_datasets' (plural).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. No prerequisites (e.g., dataset must exist) or context for deletion. Sibling tools include delete_datahub_datasets, but no differentiation is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, but the first sentence misleadingly suggests a read-only tracking function. The description adds confusion rather than clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is irrelevant and misleading, making the description less concise and adding unnecessary confusion.
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?
Without an output schema, more behavioral context is needed (e.g., effects, reversibility). The description only states deletion without further details.
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 coverage is 50% with only customerContext described. The description does not explain the id parameter or provide any additional parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The second sentence clearly states deletion, but the first sentence about tracking spend contradicts the tool's actual purpose, causing confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_budget or list_budgets, and no indication of prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, but description says 'Returns...' implying a read-only operation. This contradicts annotations and fails to disclose potential destructive behavior 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, but first sentence is a general statement about Cloud Diagrams not directly about the tool's action. Could be more direct and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, the description lacks details on return value, layer concept, and examples. Leaves significant gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so schema already documents most parameters. Description adds context that at least one component type array is required, but does not elaborate on 'p' or 'link' parameters beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description talks about 'Cloud Diagrams' but tool name is 'get_statussheet_components', causing confusion. It states 'Returns the specified components of a diagram layer' but does not clearly differentiate from sibling tools like 'get_cloud_diagram_components'. The purpose is muddled.
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?
Provides minimal guidance: 'Provide at least one component type with one or more IDs in the request body'. No mention of when to use this tool versus alternatives, nor exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, which align with creating an asset. However, the description adds no behavioral details beyond what annotations already convey, such as idempotency, side effects, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) but the first sentence is generic and could be removed. It front-loads the action but does not earn its place with specific details. Conciseness is adequate but not optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with zero required fields, no output schema, and many siblings, the description fails to provide sufficient context. It does not explain what an asset is, how parameters like mode or type affect the creation, or what the outcome looks like.
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 only 20% (one parameter described), but the description does not provide any parameter guidance. The parameter names (mode, type, rootEmail, accountName) are left unexplained, relying solely on their names which may be ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Creates a new asset' which gives a general purpose, but it is vague and does not differentiate from many other create_* siblings (e.g., create_account_role, create_budget). The first sentence 'Manage cloud resources or services' is overly broad and does not specify what constitutes an asset.
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 like create_account_role or create_budget. There is no mention of prerequisites, required parameters, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'List and manage,' which implies mutating behavior, but the annotations declare readOnlyHint=true and destructiveHint=false. This directly contradicts the read-only nature of the tool, making the description misleading about 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but includes the redundant and misleading 'List and manage' phrase, which weakens its precision. It is not front-loaded with the core purpose, though it is concise overall.
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 simple retrieval nature and readOnly annotations, the description minimally states what it returns. However, with no output schema, it does not clarify the structure of the returned contract or any error conditions, leaving some gaps for a getter tool.
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 only 33% (customerContext has a description, contractID and customerID do not). The description adds no explanation of these required parameters, such as their purpose or format, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it 'Returns the specified contract,' which clearly indicates a retrieval operation. However, the opening phrase 'List and manage' is misleading and suggests broader functionality than the tool name implies, undermining clarity slightly.
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 mentions the caller type (T1/T2 PartnerOps) but provides no guidance on when to use this tool versus alternatives like list_contracts or get_contract_template. No exclusions or context about selection criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description adds no behavioral context beyond stating 'Deletes'. It does not describe that deletion is irreversible, whether any permissions or dependencies exist, or what the side effects are. With annotations covering the destructiveness, the description could still add value by mentioning permanence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short with two sentences. The first sentence is misleading and irrelevant to the delete action; it could be removed. The second sentence is concise. Overall, it is minimally acceptable but has unnecessary content.
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 with two parameters and no output schema, the description should cover permanence, authorization requirements, and consequences. It only states the basic action. Given the low complexity, a better description would add details about confirmation or revertibility.
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 50% (only customerContext has a description). The description does not mention or explain either parameter. For the 'id' parameter, which has no schema description, the description offers no help. The description adds no meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Deletes the alert specified by the Id.' which clearly indicates the verb and resource. However, the first sentence about notifications is conceptually tangential and could cause confusion about the tool's purpose. The tool is well-distinguished from siblings like create_alert and update_alert.
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 delete versus alternatives (e.g., deactivating an alert). There is no mention of prerequisites, such as the alert needing to exist, or any conditions that should be checked before deletion.
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 destructiveHint: true. The description adds that it deletes 'all their associated data,' which clarifies the scope. However, it does not mention irreversibility, dependencies, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence about ingestion is irrelevant and wastes space, making the description less concise than it could be. The second sentence is clear but could be more direct.
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 bulk operation, the description lacks details on recovery, prerequisites, or differentiation from singular delete. It misses context needed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are fully documented. The description adds no additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Deletes one or more DataHub datasets and all their associated data,' which clearly identifies the action and resource. However, the first sentence about ingestion is misleading and irrelevant for a delete tool, reducing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like the sibling 'delete_datahub_dataset' (singular). There is no mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's mention of 'deletes' aligns but adds no new behavioral context. No additional traits (e.g., permissions, side effects) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, but the first sentence is verbose and introduces irrelevant functionality ('Create and manage'). The second sentence is clear. Could be trimmed to focus solely on deletion.
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?
As a destructive tool, the description lacks details on consequences (e.g., cascade effects on label assignments), return values, or required permissions. No output schema exists, so more context is necessary.
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 coverage is 50% (only customerContext has description). The tool description does not describe the 'id' parameter or add meaning beyond the schema. It misses the opportunity to clarify that 'id' likely refers to the label's unique identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Deletes the label specified by the Id' which clarifies the delete action, but the opening phrase 'Create and manage labels' is misleading and suggests a broader purpose. The tool name 'delete_label' reinforces the delete function, but the description's first sentence conflicts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_label or update_label. The description does not specify prerequisites, when not to use, or context for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The first sentence claims the tool can 'plan and automate purchases,' which implies a write or side-effect behavior, while annotations declare `readOnlyHint: true` and `destructiveHint: false`. This is a direct contradiction. The later sentences add some useful return-content context, but the misleading claim undermines the 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The three sentences are reasonably compact and the concrete details appear in the second and third sentences. However, the first sentence is marketing language about planning, automating, and optimizing that does not describe the tool's actual behavior and should be removed or rewritten.
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?
There is no output schema, so the description should provide more detail about the returned 'analysis metrics and time-bucketed eligible spend' fields. It also fails to clarify how `managementAccountId` identifies the organization and how `customerContext` applies for DoiT employees, leaving gaps for correct invocation and interpretation.
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 only 20%, so the description must compensate. It adds meaning for `serviceId` (commitment type) and `granularity` (bucket size, defaulting to `day`), but it leaves the required `managementAccountId` unexplained despite referencing the AWS organization, and it does not address `X-Tenant-Id` or `customerContext`. This is partial compensation at best.
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 returns a recommendation for one commitment type (`serviceId`) on the AWS organization, including analysis metrics and time-bucketed eligible spend. This distinguishes it from a list-style sibling like `list_aws_recommendations`, though it does not explicitly name that sibling and the opening sentence is broad product marketing.
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 the tool: when you need a recommendation for a specific commitment type and want eligible-spend buckets sized by `granularity`. However, it gives no explicit alternatives or conditions, such as when `list_aws_recommendations` or `get_commitment` would 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 already declare destructiveHint=true, so the description's 'Deletes' is consistent but adds no additional behavioral context (e.g., reversibility, cascading effects, permission requirements). The confusing first sentence does not aid transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but the first sentence ('Define how costs are distributed...') is unnecessary and could be removed to improve conciseness. The structure is otherwise adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (delete by ID) and annotations providing destructive hint, the description is partially complete. However, it lacks context about when to use this tool, potential impacts on cost distribution, and any dependencies like required role permissions.
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 adds meaning to the 'id' parameter (specifies which allocation to delete), which lacks a schema description. The 'customerContext' parameter is described in the schema. With 50% schema coverage, the description partially compensates but does not detail the id format or 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 clearly states the action ('Deletes') and resource ('allocation'), and the identifier ('Id'). This distinguishes it from sibling tools like create_allocation, update_allocation, and get_allocation. However, the initial sentence 'Define how costs are distributed...' is a general definition of an allocation, not the tool's purpose, adding minor confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., update_allocation or disabling an allocation). It does not mention prerequisites, such as the need for the allocation to exist, or any consequences of deletion.
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 mark destructiveHint=true, so description correctly implies destructive action. But it adds no additional behavioral context such as whether deletion is permanent, requires specific permissions, or has cascading effects. Minimal 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences; the first sentence is unnecessary context about annotations in general and could be removed. The core deletion instruction is clear but could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should cover return behavior, error cases, or side effects. It leaves these unaddressed. For a destructive operation, more context is needed for safe 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?
Input schema covers 50% of parameters (customerContext has a description, id does not). The description merely references 'the Id' but does not explain the id parameter format or the optional customerContext. Schema coverage baseline is 3, and description adds little.
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 'Deletes the annotation specified by the Id,' specifying the verb and resource. It distinguishes from sibling tools like create_annotation, update_annotation, get_annotation, and list_annotations. However, the first sentence about 'Custom notes added to cost data' is redundant and may confuse, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_annotation or list_annotations. The description does not provide context on prerequisites, idempotency, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description's 'Deletes a user' is consistent. However, the description adds no extra behavioral context (e.g., irreversibility, permission requirements, cascading effects). It meets the minimum bar given the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description has two sentences, the first being generic ('Manage users who have access to the DoiT platform.') which adds little value. The second sentence is direct. It could be more concise by removing the first sentence.
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 operation with no output schema, the description is too sparse. It does not mention the outcome (e.g., confirmation, return status), whether the deletion is permanent, or any effects on related data. It lacks completeness for safe usage.
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?
With only 50% schema description coverage, the description does not explain the parameters at all. The 'customerContext' parameter is described in the schema, but the required 'id' parameter lacks any description in both schema and tool description. The description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool deletes a user, which aligns with the tool name 'delete_user'. It distinguishes from sibling user tools like invite_user, update_user, and validate_user by explicitly using 'Deletes a user'.
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, such as when a user should be removed versus disabled, or any prerequisites like ownership of the user. It only states the action without 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 provide readOnlyHint true, destructiveHint false, and openWorldHint true, so the safety profile is known. The description adds caller scope and the DPMA/PMA relationship, but the opening 'Manage' wording is ambiguous and could imply mutating mappings. This is not a hard contradiction because the operation is explicitly described as 'Lists', but it does not enrich behavioral transparency much beyond existing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core definition is relatively short, but the first sentence is overly broad and not needed for this tool's actual purpose. The description could be improved by removing the 'Manage... and list program management accounts' fragment and leading with the concrete listing statement.
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 five parameters, no output schema, and a closely related sibling tool bank, the description should clarify what an end-customer mapping looks like, how records are scoped, and whether pagination or special headers affect results. It provides only who can call and the main identifiers, leaving important operational context missing.
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 only 20%, and the description merely names `dpmaId` and `resellerPmaAccountId` as identifiers without explaining their meaning or format. It does not compensate for the lack of schema descriptions for `includeRevoked`, `X-Tenant-Id`, or the full `customerContext` semantics.
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 core statement that the tool 'Lists the end-customer AWS account mappings under a reseller's program management account' is clear and specific, with the two key identifiers named. It loses the top score because the opening sentence describes a broader 'Manage' role and 'list program management accounts,' which is closer to sibling tools and could confuse an agent.
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 authorization context—who may call the tool—but does not explain when to choose this over the very similar sibling `list_billing_transfer_end_customers_by_reseller` or `list_billing_transfer_reseller_accounts`. There is no when-to-use guidance or exclusion of alternative 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 destructiveHint and readOnlyHint false, so the tool mutates state. The description adds only 'help improve response quality', which is vague. It does not clarify what gets changed (e.g., feedback record created, model retraining triggered) or any side effects like rate limits or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but the first sentence 'Interact with Ava, DoiT's AI-powered cloud assistant' is somewhat redundant. The second sentence carries the true purpose. It is efficiently short, but the first sentence could be trimmed without loss.
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 destructive nature, nested schema, and no output schema, the description is minimally adequate. It does not explain where to find conversationId/answerId, how customerContext works, or what happens after submission. It lacks guidance for proper usage in the broader context of Ava interactions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (all four parameters have descriptions), setting a baseline of 3. The description adds no additional meaning beyond what the schema provides for parameters like conversationId, answerId, or feedback. No syntax, format, or relationship between parameters is clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'submit feedback' and the resource 'Ava answer'. While it begins with a broad 'Interact with Ava', it quickly narrows to feedback submission. It differentiates from sibling tools like ask_ava_streaming and ask_ava_sync by its distinct purpose, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not advise against using it for asking questions, nor does it mention prerequisites like having a conversation or answer ID. The description leaves usage context entirely implicit.
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 destructiveHint=true and readOnlyHint=false, consistent with deletion. The description adds no further behavioral context (e.g., whether deletion is permanent, cascading effects, or required permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences but includes a superfluous first sentence about managing and getting reports, which is irrelevant to deletion. Could be condensed to a single clear 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 delete tool with two parameters and no output schema, the description is adequate but marred by the misleading first clause. Missing details on prerequisites or effects, but not critically incomplete given the tool's straightforward nature.
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?
With 50% schema description coverage, the description does not compensate. It fails to explain the 'id' parameter or clarify the purpose of 'customerContext,' which already has a good schema description. The description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'Deletes the specified Cloud Analytics report,' clearly identifying the action and resource. However, the first sentence about 'Manage Cloud Analytics reports and get reports data' is misleading and suggests broader functionality not supported.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other delete or report management tools. Among siblings, there are many delete operations and report-specific tools (create_report, update_report, list_reports), but no distinctions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'Read and update' but annotations declare readOnlyHint: true. This is a direct contradiction: the tool is read-only, yet the description implies it can update. No other behavioral details (pagination, response format, etc.) compensate. This is a serious inconsistency, so score 1.
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 three sentences, front-loaded with the (misleading) 'Read and update' but still compact. It packs in the scope, error case, and permission requirements without unnecessary verbosity. However, the misleading update phrase detracts from overall structure, so not a 5.
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 get-customer tool, it covers the key constraints: token scoping, 403 behavior, required permissions. It does not mention the customerContext parameter or when to include it, which is important for DoiT employees. The contradiction about updating also undermines completeness, so while it has substantial context, it misses critical aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: customerContext lacks a description in the schema, but customerId has no schema description. The description adds crucial semantics for customerId (must match token, 403 if not), but says nothing about customerContext, which is required for DoiT employees. It partially compensates for the undocumented parameter but leaves a gap, hence 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it 'Read and update your organization's general settings' and 'Returns the customer,' which conveys a general purpose. However, the tool is named get_customer and the description itself emphasizes returning data, while the 'update' part is misleading and contradicts the read-only nature. It does identify the resource and scope, but the ambiguity lowers clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use the tool: the customerId must match the bearer token's customer, and it explicitly states the 403 error for mismatches, and required permissions. It does not compare with sibling tools like search_customers, but the scoping constraint gives practical usage guidance, earning a 4.
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. The description adds useful behavioral context beyond annotations by specifying the required 'UsersManager permission' and the ownership scope 'owned by the authenticated tenant.' However, it does not describe return format, error cases, or pagination, and the vague 'Manage' wording slightly muddies the read-only nature. No annotation contradiction is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description has two sentences and is not excessively long, but the first sentence 'Manage country-based access to tenants in your customer hierarchy' is a generic mission statement that does not directly describe the getter operation and could mislead. The second sentence is concise and useful. Overall it is acceptable but not tightly scoped.
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 get-by-ID tool with strong annotations, the description covers permission and ownership. But it does not define what a 'custom region' is, how the customRegionId should be obtained (e.g., from list_geographic_access_custom_regions), or how X-Tenant-Id and customerContext interplay. Given the existence of many closely related sibling tools, this is a noticeable 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?
Schema description coverage is only 33%, with only 'customerContext' described in the schema. The description does not explain 'customRegionId' or 'X-Tenant-Id' at all. The parameter names give some clues, but the description fails to compensate for the low schema coverage, leaving an agent without a clear understanding of required tenant context or how to obtain the customRegionId.
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 return action: 'Returns a custom region owned by the authenticated tenant.' This is a clear verb+resource pairing. However, the opening sentence 'Manage country-based access to tenants in your customer hierarchy' is a broad domain statement rather than a precise operation, and no sibling tool is named for differentiation, so it doesn't fully earn 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 gives no guidance on when to use this tool instead of list_geographic_access_custom_regions, create_geographic_access_custom_region, or related geographic access scope tools. It mentions a permission requirement but no usage context or exclusions, so an agent is left to infer the appropriate invocation scenario.
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 states 'updates' and 'add or remove licenses,' which aligns with annotations (destructiveHint=true, readOnlyHint=false). It adds context about the type of update but does not disclose potential side effects like billing changes or irreversibility. Annotations already cover the destructive nature, so the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but the first sentence ('Manage cloud resources or services') is vague and adds no value. The second sentence is specific. Could be more concise by removing the first sentence. Adequate length but slightly padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and medium complexity, the description should explain the return value (e.g., the updated asset object) and potential errors. It lacks information on prerequisites, success/error responses, or async behavior. The description is incomplete for a mutation tool.
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 mentions 'add or remove licenses,' which relates to the 'quantity' parameter, but it does not explain the format or semantics of 'id' or 'quantity' (e.g., positive/negative values). With only 33% schema coverage, the description should compensate but adds minimal detail beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing asset, specifically subscriptions like G Suite or Office 365, to add or remove licenses. However, the first sentence is vague ('Manage cloud resources or services'), and the tool name 'id_of_asset' is ambiguous for an update operation. The description distinguishes it from siblings like create_asset and list_assets, but not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying licenses of existing subscriptions, but it does not provide explicit guidance on when to use it vs. alternatives (e.g., when creating a new asset vs. updating). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description reinforces this by saying 'Deletes a CloudConnect document.' It adds a bit of context by naming the specific resource and account type, but does not detail side effects, reversibility, or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes an extraneous first sentence that broadly describes cloud provider management. The relevant delete action is front-loaded only after that sentence, so the structure could be tighter.
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 delete operation with two straightforward parameters, the description is minimally adequate. It lacks details on return values, error cases, or whether the account role must exist, but the low complexity keeps these gaps from being severe.
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 adds no parameter-level meaning; the schema covers customerContext but not accountID. However, accountID is self-explanatory by name and is the required parameter, so the absence of description text is not a major gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The second sentence clearly states the tool 'Deletes a CloudConnect document for an AWS account,' specifying both the verb and resource. However, the first sentence about managing cloud provider connections and checking feature availability is broader than the delete action and could distract from the core purpose.
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 create_account_role or delete_cloudflow_connection. The usage is only implied by the word 'Deletes.'
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 states it 'Returns' data, aligning with the readOnlyHint annotation and no destructive effects. It does not mention any side effects or additional behaviors, but the annotations cover the safety profile, so the description adds modest value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant information. It is well-structured and directly communicates the core functionality without unnecessary detail.
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 purpose is clear, the description lacks contextual information about parameters, input requirements, or typical use cases. It does not mention the optional customerContext or the required invoiceMonth format, leaving the caller to infer from the schema alone.
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 does not explain any of the three parameters (X-Tenant-Id, invoiceMonth, customerContext). It only implicitly references invoiceMonth via 'month-over-month', but provides no details on expected formats, optionality, or usage of the others.
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: explaining month-over-month changes in invoiced cloud costs, and specifies it returns cost changes per payer. This is specific and distinguishes it from broader invoice or cost tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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 (e.g., get_entity_invoice_explainer, get_invoice). It does not mention prerequisites, context, or scenarios where this tool is preferred.
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 clearly label the tool as readOnlyHint=true and destructiveHint=false, so the safety profile is well established. The description adds minimal behavioral context by mentioning 'returns a single snapshot', but does not disclose details like validity guarantees, permissions required, or behavior on invalid IDs. Given annotation coverage, a score of 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 extremely concise with two sentences that front-load the context and state the action without any wasted words. Every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides basic context about cloud diagrams and what the tool returns. However, it omits any indication of the output structure (no output schema exists), how this snapshot relates to other diagram tools, or typical use cases. It is minimally viable but lacks completeness for a tool with multiple siblings and no output schema.
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 only 33% (only customerContext has a description). The description does not explain what the required parameters 'id' and 'snapshot_id' represent or where to obtain them. It vaguely suggests 'by its ID', but adds no semantic value beyond the schema. Therefore, the description fails 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns a single snapshot of a diagram layer by its ID, with a helpful introductory context about cloud diagrams. However, it does not explicitly differentiate this tool from siblings like list_cloud_diagram_layer_snapshots or get_cloud_diagram_components, which share the same domain.
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 about when to use this tool versus alternatives such as list_cloud_diagram_layer_snapshots (which lists snapshots) or other diagram tools. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a couple of behavioral details beyond annotations: it does not update Firestore channel documents and does not require a CloudFormation stack ID. The annotations already indicate destructive and open world behavior. The description could be improved by mentioning side effects, permissions required, or rate limits, but the provided details are helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but the first sentence is overly broad ('Manage cloud provider connections and check feature availability') and could be misleading. The core action is in the second sentence. A more concise, front-loaded description would improve clarity. The current structure is adequate but not optimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description should explain what the tool returns (e.g., the created/updated document). It also does not define what a CloudConnect document is, nor does it elaborate on 'check feature availability.' The tool has 6 parameters and annotations indicating destructive behavior, but the description lacks details on the expected outcome and broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema itself documents each parameter's meaning and constraints. The tool description does not elaborate on parameters beyond what the schema provides. It mentions 'check feature availability' which could relate to enabledFeatures, but this is not explicit. Therefore, the description adds minimal value in this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates or updates a CloudConnect document for an AWS account. The verb 'creates or updates' and the resource 'CloudConnect document' are specific. However, the first sentence 'Manage cloud provider connections and check feature availability' is vague and not directly aligned with the tool's primary action. It differentiates from a CloudFormation variant but not from sibling tools like delete_account_role or update_aws_feature.
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 comparison to the CloudFormation variant, noting that this endpoint does not update Firestore channel documents or require a CloudFormation stack ID. This offers some context for choosing this tool over an alternative. However, it does not explicitly state when to use this tool versus other account role management tools (e.g., delete_account_role), nor does it mention prerequisites or typical scenarios.
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?
Description adds the important constraint that eventIds and time ranges are mutually exclusive, which is not in the schema. Annotations already indicate destructive and open-world behavior, so the bar is lower. However, it does not disclose irreversibility or data affected beyond filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes an irrelevant first sentence about ingestion, which is misleading and wastes space. The key deletion behavior and filter constraint are present, but the opening sentence should be removed for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description is incomplete. It does not mention post-deletion behavior, response format, required permissions, or safety warnings. The filter constraint is useful but insufficient for an agent to fully understand the tool's impact.
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 adds value by explaining that eventIds and time ranges are mutually exclusive, which clarifies parameter interaction beyond the schema. Schema coverage is high (80%), but this constraint is not in schema descriptions, so the description compensates well.
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 'Deletes specific events using filters', which aligns with the tool name. However, the first sentence about ingestion is misleading and could confuse the agent about the primary action. The distinction from sibling delete tools is implicit via the 'datahub_events’ context, but not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like delete_datahub_dataset or others. The only usage hint is the mutual exclusivity of filters, but no context on when deletion is appropriate or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description needs to disclose behavioral traits. It states the tool marks the suggestion as dismissed and removes it from the pending list, which is useful. However, it does not mention what happens after dismissal (e.g., can it be undone? any side effects?) or the need for linking to a budget for acceptance, which is partially covered but not fully.
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 core purpose. It wastes no words, but could be more direct (the 'or dismiss' part might cause confusion). Overall, it's efficient but slightly ambiguous.
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 simple tool, the description covers the basic action and outcome but leaves gaps: it doesn't explicitly state the input parameter (id) semantics, doesn't mention if acceptance requires a budget link (suggested but not detailed), and doesn't clarify the relationship with accept_budget_suggestion. It's sufficient for a simple tool 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 is minimal (only 'id' required, no descriptions), and the description does not explain what 'id' represents or how to obtain it boundary. With schema_coverage being low (no property descriptions), the description fails to compensate by clarifying the parameter's meaning or format.
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: handling AI-generated budget recommendations by accepting or dismissing, with a specific focus on dismissing and marking as no longer pending. It distinguishes from siblings like accept_budget_suggestion, but it slightly conflates the action by mentioning both accept and dismiss, though the primary verb (dismiss) is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the tool is used for dismiss actions but mentions 'accept' as an option without explicitly directing to accept_budget_suggestion. It lacks explicit when-to-use/when-not-to-use guidance and does not clearly differentiate from the accept sibling beyond the tool name.
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 clearly indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds that it explains changes and returns cost changes, which is some behavior. But it doesn't disclose details like whether it handles multiple currency adjustments, pagination, or formatting, though with readOnlyHint, a mid-score is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, clear and to the point. It front-loads the core purpose and scope. No wasted words, but could perhaps be more structured with a line break, still fine.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is moderate complexity (4 params, no output schema, some annotations), the description provides basic purpose and scope. It doesn't explain the return format (what 'returns invoiced cost changes' means in detail) or how to handle customerContext for different user types, which is partially described in schema. For a read-only analysis tool, it's 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 only 25%: only customerContext has a description. The description itself does not explain what billingProfileId or invoiceNumber mean or how they relate to the invoice. While invoiceNumber pattern is in schema, the description provides no extra semantics. It fails to compensate for the low schema coverage, leaving two required params underdocumented.
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 explains month-over-month changes in invoiced cloud costs, with a specific scope (invoice owned by billing profile in authenticated tenant). It distinguishes from siblings like list_invoices and get_invoice which handle listing/retrieval, not explanatory analysis.
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 need to explain month-over-month cost changes for an invoice. It doesn't explicitly state when not to use it or compare to similar tools like get_billing_explainer_per_payer. The sibling get_billing_explainer_per_payer might be an alternative, but no comparison is given, leaving some ambiguity.
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 behavioral detail: recommendations are keyed by commitment type and a type appears only if onboarded and available, which helps agents interpret missing keys. Pagination and response shape are not described, but for a read-only list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences and reasonably compact, but the first sentence is largely product marketing ('Evaluate... optimize cloud costs with PerfectScale for Commitments') and adds little operational value. The more precise 'Returns commitment purchase recommendations...' sentence should be 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?
Without an output schema, the description does a decent job explaining return semantics: keying by commitment type and conditional presence when onboarded. However, it omits how the required managementAccountId parameter is used, says nothing about pagination or result shape, and does not distinguish among the many adjacent AWS commitment and recommendation tools in the sibling list.
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 only 33%, so the description needs to compensate for the undocumented parameters. It does not explain how managementAccountId is used, what X-Tenant-Id means, or how to choose between customerContext and X-Tenant-Id. The phrase 'AWS organization' loosely hints at managementAccountId but does not meaningfully add semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns commitment purchase recommendations for the AWS organization, keyed by commitment type (`compute`, `database`), and explains conditional presence. It is specific enough to distinguish from generic tools like list_optimization_recommendations, though it does not explicitly differentiate from close AWS siblings such as list_aws_savings_plans or get_aws_recommendation.
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 opening sentence places the tool in a broad workflow: evaluating commitments, planning and automating purchases, and optimizing cloud costs. However, this is more marketing language than concrete selection guidance. It does not explain when to use this tool versus list_aws_planned_purchases, list_aws_reserved_instances, or get_aws_recommendation, nor does it provide 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail: pagination with pageToken, when to stop paginating, distributor-only access, and that handshake status is included. It doesn't fully describe the response shape, but for a read-only list this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The pagination instructions are clear and the description is not overly long. However, the first sentence about 'Manage AWS billing-transfer mappings...' is broad, redundant with the listing focus, and could mislead. Some trimming would make it sharper.
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 paginated list tool with no required parameters, the description covers scope, returned content, and pagination. But with no output schema and multiple undocumented optional parameters, the description leaves gaps around the exact response format and the meaning of maxResults and X-Tenant-Id.
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 only 25%, and the description compensates only for pageToken by explaining the pagination loop. maxResults and X-Tenant-Id remain unexplained, and customerContext is described only in the schema, not reinforced in the description. This is too little compensation for four parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a listing operation for the caller's program management accounts and reseller tenants, including handshake status. It distinguishes from sibling billing-transfer tools by focusing on PMAs and distributor scope, though the opening 'Manage AWS billing-transfer mappings' is broader than the actual read-only list and slightly muddies 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 gives useful context by stating 'Distributor-only' and explaining pagination behavior. However, it does not explicitly say when to use this tool over sibling tools like list_billing_transfer_reseller_accounts_with_tenants or list_billing_transfer_end_customers, and it gives no exclusions beyond the distributor restriction.
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 mutation (readOnlyHint=false, destructiveHint=true). Description adds only permission requirement, not additional behavioral context like overwrite behavior or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste, front-loaded with action. Could include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers creation and permission but lacks output info, error cases, or naming constraints. Adequate for a simple create tool with good schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds no extra parameter meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb ('creates') and resource ('custom color theme'), distinguishing it from update_theme, delete_custom_theme, and get_theme 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?
Mentions required permission but no guidance on when to use vs alternatives (e.g., update_theme) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds meaningful behavioral context by explaining that region, iamStatus, and lastRefreshTime are inherited from the parent DPMA root, and that the reseller node carries no IAM/region metadata. This goes beyond the annotations and clarifies the data structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description starts with a broad, somewhat extraneous phrase about managing mappings, then gets to the core purpose. It includes useful detail about inherited metadata but could be more streamlined. The two-sentence structure is acceptable but the first sentence is vague and could be removed without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives good context on the output (reseller nodes with tenants) and metadata inheritance, but it lacks explanations for the parameters and does not clarify the exact conditions under which the tool is used vs other listing tools. With no output schema and low parameter coverage, the description could be more complete, but it covers the main functional aspect.
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 does not mention any of the three parameters (X-Tenant-Id, includeRevoked, customerContext). Schema description coverage is only 33% (only customerContext has a description), and the description does not compensate by explaining what includeRevoked or X-Tenant-Id mean, or how they affect the results.
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 reseller PMA nodes with their connected end-customer tenants, and explicitly identifies it as the reseller-tier analog of a specific API. This distinguishes it from sibling tools like list_billing_transfer_program_management_accounts and list_billing_transfer_reseller_accounts by specifying the 'reseller-tier' scope and the inclusion of tenants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus the sibling list_billing_transfer_program_management_accounts, list_billing_transfer_reseller_accounts, or list_billing_transfer_end_customers_by_reseller. The description mentions it is 'the reseller-tier analog' of another API, but does not explain in which scenarios one would prefer this over the other listing 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds useful context that the result is a canonical ISO country catalogue, not a per-tenant access list. However, it does not detail auth expectations, tenant scoping behavior, or whether the catalogue is global or varies by context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and mostly efficient, with the key return behavior clearly stated. However, the first sentence 'Manage country-based access to tenants in your customer hierarchy' is generic, somewhat misleading, and does not earn its place next to the sharper second sentence.
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 optional parameters, the description provides enough information: the tool returns the canonical ISO 3166-1 alpha-2 country catalogue. The lack of an output schema is partially compensated by the explicit return description, and sibling tool names give surrounding context on geographic-access workflows.
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 50%: customerContext is documented, but X-Tenant-Id is not. The description's mention of 'tenants in your customer hierarchy' loosely connects to the parameters but does not explain how either parameter affects the returned country catalogue. Overall, it adds only domain context rather than specific parameter semantics.
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 second sentence clearly states the tool 'Returns the canonical ISO 3166-1 alpha-2 country catalogue used by geographic access policies,' naming a specific verb and resource. However, the first sentence uses 'Manage country-based access,' which implies broader write capabilities and slightly weakens the clarity and differentiation from sibling 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 this tool is for retrieving the standard country catalogue relevant to geographic access policies, which gives the agent a clear domain context. It does not explicitly state when to prefer this over sibling tools like custom-region or access-scope tools, nor does it provide 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 adds significant behavioral context beyond the annotations: it details role-based tag visibility (full set for DoiT employees, customer_tag namespace stripped for customers) and guarantees an empty array when no tags are visible. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's extra context is valuable 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core explanation is concise and well-organized, but the first sentence 'Create and manage support tickets with DoiT' is off-topic boilerplate that wastes space and could confuse. Removing it would make the description more focused. The rest of the content earns its place by explaining response behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema present, the description appropriately explains the return shape: an array that is always present and may be empty. It also covers role-based response differences, which is essential for agents operating with different token contexts. Missing error-case behavior is a minor gap, but overall the description is complete for a simple read-only tool.
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 adds no parameter-specific meaning; it never mentions ticketId or customerContext. Schema description coverage is only 50% (customerContext is described, ticketId is not), so the description should compensate for the undocumented ticketId but does not. ticketId's semantics rely solely on its name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function in the second sentence: 'Returns the tags currently set on a support request.' This is a specific verb+resource that distinguishes it from sibling tools like add_ticket_tags and remove_ticket_tags. However, the opening sentence 'Create and manage support tickets with DoiT' is misleadingly broad and could suggest a different purpose, preventing a perfect score.
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 this tool is for reading existing tags, but it never explicitly states when to use it versus alternatives like add_ticket_tags or remove_ticket_tags. It does provide useful context about caller types (DoiT employee vs customer), but that is more about response shaping than selection guidance. There are no clear 'use when' or 'instead of' instructions.
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 destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds negative behavioral constraints (no Firestore updates, no CloudFormation stack ID, no StackSet member role ARNs), which is useful. However, it does not disclose what destructive changes occur to existing enabled features or account state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, but the opening sentence 'Manage cloud provider connections and check feature availability for connected accounts' is vague and does not earn its place for an update-specific tool. The remaining two sentences are focused and useful, but the first sentence adds noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is present, and the description does not explain return values or the effect of updating enabledFeatures (e.g., whether omitted features are disabled). It provides some context via the CloudFormation contrast, but for a destructive update tool, it should clarify what changes are applied to the existing CloudConnect account.
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 80%, and the schema already provides detailed parameter descriptions, especially for enabledFeatures and the conditional s3Bucket/s3BucketRegion requirements. The tool description itself adds little parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core action: 'Updates an AWS feature for an existing CloudConnect account.' This is a specific verb+resource combination. The first sentence is broader and somewhat generic, but the second sentence disambiguates the tool from feature-checking and CloudFormation-related operations.
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 useful exclusions: 'Unlike the CloudFormation variant, this endpoint does not update Firestore channel documents, require a CloudFormation stack ID, or handle StackSet member role ARNs.' This tells the agent when not to use this tool, though it does not name the exact sibling alternative or give explicit positive usage conditions.
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 destructiveHint=true, so the description's mention of deletion aligns. However, no additional context is added (e.g., irreversibility, required permissions, or side effects). The description meets the baseline but does not 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence ('Interact with Ava...') is redundant and not specific to deletion, adding unnecessary fluff. The core purpose is in the second sentence. While short, it could be more concise and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, no output schema, annotations present), the description covers the basic functionality. However, it omits any details about the result of deletion (e.g., success/failure indication) or potential side effects, making it somewhat incomplete.
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 ties the conversationId parameter to the object being deleted ('by its ID'), adding meaning beyond the schema's bare string type. The customerContext parameter is already described in the schema. This provides sufficient context for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Deletes') and the resource ('Ava conversation'), making it easy to distinguish from sibling tools like ask_ava_streaming or ava_feedback. The verb and target are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., not mentioning that it's for deleting completed conversations). There is no advice on prerequisites, permissions, or scenarios where deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only and non-destructive. The description adds meaningful return semantics: identity, onboarding status, 30-day ESR/savings, YTD/lifetime totals, potential savings, and the data behind Cost Summary and Commitment Coverage charts. It also notes that lifetime is bounded by the parent organization's onboarding start. No annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The field list is well-structured and valuable, and the core purpose appears early. However, the first sentence is irrelevant marketing fluff about PerfectScale capabilities that doesn't describe what this tool does; it should be removed. The description is longer than necessary because of this misleading opener.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates well by enumerating the Overview fields in detail. However, it leaves required parameter semantics to the schema and does not clarify how managementAccountId and memberAccountId relate, nor does it explicitly point to list_aws_member_accounts for the list-item field definitions.
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 only 25%, and the tool description does not mention managementAccountId, memberAccountId, customerContext, or X-Tenant-Id at all. The parameter names and regex patterns provide minimal clues, but for a tool requiring two 12-digit account IDs, the description should clarify which is the parent management account and which is the target member account.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns a single member AWS account with the same list-item fields as List member accounts plus Overview time series data, and it contrasts this with fetching every member account. However, the opening sentence about evaluating commitments, planning purchases, and optimizing cloud costs is off-purpose and could mislead an agent about the tool's actual operation.
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 explicitly says to use this when a single member Console Overview is needed in one call 'without fetching every member account', which implies the sibling list tool for bulk retrieval. The guidance is clear but doesn't explicitly name the exact sibling or provide exclusion cases.
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 meaningful behavior beyond them: it documents the pageToken pagination loop and the stop condition. It also clarifies that omitting filters returns all Savings Plans. The marketing first sentence is misleading, but the operational description 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The pagination and filter guidance are concise and well placed after the first sentence. The opening sentence is promotional fluff that suggests planning and automation capabilities this read-only list endpoint does not actually provide, so not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers pagination and main filters, which are common invocation pitfalls. However, it omits maxResults behavior, tenant/header handling, and any explicit guidance on how Savings Plans listing relates to the many AWS commitment siblings, so the agent still lacks some selection and invocation 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?
With schema description coverage at only 14%, the description carries real weight. It explains type and status filters and pageToken, but it does not cover maxResults, X-Tenant-Id, or managementAccountId beyond the phrase 'AWS organization.' This is partial compensation for a low-coverage 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 core operation is clear: 'Returns a paginated list of Savings Plans for the specified AWS organization,' naming a specific verb, resource, and scope. However, the opening marketing sentence about evaluating commitments and automating purchases muddies the immediate purpose, and it doesn't explicitly differentiate from close siblings like list_aws_reserved_instances.
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 useful filter guidance ('Omit both filters to return all plans') and clear pagination instructions. It does not, however, say when to prefer this tool over alternatives such as list_aws_reserved_instances, list_aws_planned_purchases, or list_aws_recommendations, leaving selection context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only adds domain context (EDP agreements) but omits crucial behaviors like pagination, read-only nature, rate limits, or authentication requirements. The agent lacks information on how the tool behaves beyond its basic function.
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 consists of two efficient sentences. The first sentence front-loads the core action and resource, while the second provides essential context. No redundant or extra words are 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?
The description explains the type of contracts but does not describe the return fields or pagination behavior, despite no output schema being available. It is adequate for a simple list tool but leaves gaps in understanding the full response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents all five parameters well. The description adds no additional meaning to the parameters beyond what the schema provides (e.g., explaining `filter` syntax or `sortBy` values). Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a list of commitment contracts from the DoiT Commitment Manager, identifying them as EDP agreements. It uses a specific verb and resource, distinguishing the tool from the sibling `get_commitment` which returns a single commitment.
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 explains what the tool does but provides no guidance on when to use it versus alternatives like `get_commitment` or other list tools. There are no exclusions or when-not-to-use hints, leaving the agent to infer usage context solely from the purpose.
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 operative verb 'Returns' aligns with that safety profile — no contradiction. The description adds genuinely useful context beyond the annotations: the UsersManager permission requirement and the tenant-ownership scoping of results. The misleading 'Manage' opener creates mild tension with readOnlyHint but is overridden by the explicit 'Returns' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
At roughly 30 words the description is appropriately sized, and the permission requirement earns its place. But the core listing action is not front-loaded — the opening sentence is a domain-level 'Manage' statement that is both redundant with the tool name and potentially misleading, while the actual function ('Returns...') is buried in sentence two.
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 list operation whose annotations already cover safety, the description is minimally adequate: it names the result scope and the required permission. But with no output schema, no pagination details, an unexplained domain term ('ready'), an undocumented X-Tenant-Id, and no differentiation within a large geographic-access sibling family, an agent is left with noticeable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
customerContext has a strong schema description covering the DoiT-employee vs direct-customer distinction, and the description's 'owned by the authenticated tenant' phrase loosely illuminates tenant-identity semantics. However, at exactly 50% schema coverage, X-Tenant-Id remains entirely undocumented in both schema and description, and the description does not compensate with parameter-level detail.
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 second sentence states a specific verb and resource: 'Returns the ready custom regions owned by the authenticated tenant,' which clearly identifies the listing action and distinguishes it from country-listing and single-region getter siblings. However, the opening sentence uses the family-level verb 'Manage country-based access to tenants,' which describes the whole CRUD domain rather than this specific tool, preventing 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a useful prerequisite ('Requires the UsersManager permission') and ownership scoping ('owned by the authenticated tenant'), which implies when this tool applies. However, it never explicitly routes away from near siblings such as list_geographic_access_countries or get_geographic_access_custom_region, so the when-to-use guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness. The description adds the permission requirement, but does not disclose additional behavioral traits like irreversibility or effect on active themes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler words: verb, object, and permission requirement are included efficiently.
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 basic action and permission but lacks details on success/error responses, cascading effects, or validation, which would be helpful for a delete tool without an output schema.
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?
With 50% schema description coverage, the description adds no new meaning to the 'id' parameter beyond stating it's the identifier. The 'customerContext' is already described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Deletes' and the resource 'custom theme specified by the Id', distinguishing it from sibling tools like create_custom_theme or update_theme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a required permission but does not explicitly guide when to use this tool vs alternatives (e.g., update_theme). Usage is implied but not contrasted.
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, openWorldHint=true, and destructiveHint=false. The description adds context about exporting 'full content' and 'all components and export metadata', but does not disclose additional behavioral traits 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 sentences with no wasted words. The first sentence provides context, the second states the action. It is front-loaded and 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 no output schema and the complexity of exporting a diagram layer, the description is adequate but lacks details on the output format structure, what 'full content' entails, and how it relates to other diagram tools. 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?
Schema description coverage is 50% (customerContext described, id not). The description does not clarify what the id parameter represents (presumably the diagram layer ID) or provide meaning beyond the schema. No parameter details are added.
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 'Exports the full content of a diagram layer as a structured JSON document', specifying a specific verb (exports), resource (diagram layer), and output format. This distinguishes it from sibling tools like get_cloud_diagram_components.
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 full layer export but does not explicitly state when to use this tool versus alternatives like get_cloud_diagram_components or get_cloud_diagram_layer_snapshot. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already mark this as a safe read operation, the description adds substantial behavior: settings are shared at customer level and identical across AWS organizations, only purchaseAccountId and commitment types vary, and pagination requires passing back pageToken until it disappears. This goes well 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description contains valuable details but opens with a promotional sentence that does not describe the tool's operational behavior. The rest is logically organized and informative, but the opening wastes space and slightly dilutes clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description does a good job explaining the return shape, cross-organization data behavior, and pagination protocol. It is incomplete only in that a few parameters and potential edge cases receive no attention, but the core calling context is present.
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 only 25%, and the description only elaborates on pageToken pagination behavior. maxResults, X-Tenant-Id, and customerContext are left unexplained in the description, so the description does not sufficiently compensate for the schema's low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns one item per onboarded AWS organization, including purchasing account and commitment settings. The opening sentence about evaluating and automating purchases is promotional and slightly vague, but the resource and verb are still identifiable.
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 useful context about when this data matters and how settings are scoped, but it never explicitly contrasts this tool with siblings like list_aws_organizations or list_aws_recommendations. Usage is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the 'same result as GET /billingtransfer/v1/end-customers' context and the callability constraint, which is useful. However, it doesn't disclose behaviors like pagination, filtering defaults (includeRevoked), or what happens if the caller lacks permission, which would be valuable 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 compact with two sentences, efficiently delivering purpose, equivalent endpoint, and callability. It's front-loaded with the action (list) and resource. Minor deduction for the API endpoint reference which, while useful, could be considered an extra detail not essential for all agents, but overall it's well-structured and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a simple purpose, no output schema, and moderate parameter complexity, the description provides adequate context: what it lists, how it's identified, and who can call it. However, it lacks information about return format or pagination, which for a list operation could be important. Still, annotations cover safety, and the description covers identity and access, so it's 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?
The schema description coverage is only 25%, meaning most parameters lack descriptions. The description compensates partially by highlighting the key parameter resellerPmaAccountId and its role in identity. However, it does not explain includeRevoked, X-Tenant-Id, or customerContext behavior beyond what the schema already provides for customerContext. The baseline is 3 because schema coverage is low, but the description doesn't fully annotate the other parameters, so it stays at 3.
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 lists AWS billing-transfer end customers by reseller PMA account ID, and explicitly references the equivalent API endpoint. It distinguishes itself from sibling tools like list_billing_transfer_reseller_accounts and list_billing_transfer_program_management_accounts by naming the specific resource (end customers) and the identifier used. However, it's slightly less precise than a direct 'List end customers' phrasing because it begins with the broader domain manage and includes an API reference.
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 lists end customers identified by resellerPmaAccountId alone, eliminating the need for dpmaId. It also specifies callability (reseller owning PMA or distributor owning DPMA), which gives clear usage guidance. While it doesn't explicitly name alternative tools for comparison, it implies the scope is narrower by referencing the API endpoint, which helps the agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive behavior, so the bar is lower. The description adds context about returned fields (handshake state, status) and the scope (belonging to the calling reseller), which is useful. It does not cover pagination or authentication, but given the annotations, 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, but the first sentence is verbose and misleading (starts with 'Manage' when the tool lists). The second sentence is clear and front-loads the action, but the overall text could be tightened to remove the confusing start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description is the only source of return information. It mentions handshake state and status but does not explain the response structure, pagination, or other fields. While the tool is a list operation, more detail about the output shape would improve completeness.
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 coverage is only 50% (X-Tenant-Id is undocumented) and the description provides no parameter guidance. It does not explain how to use customerContext or X-Tenant-Id, failing to compensate for the schema's incomplete parameter 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 reseller program management accounts (RPMA) for the calling reseller, specifying the data included (handshake state and status) and explicitly excluding end-customer tenants. It also differentiates from similar tools by noting it is the reseller-tier analog of a specific GET endpoint, and contrasts with sibling tools like list_billing_transfer_reseller_accounts_with_tenants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need reseller accounts without tenants) by stating 'without end-customer tenants' and referencing an analog endpoint. However, it does not explicitly name alternative tools or provide direct when-not-to-use guidance, leaving the decision somewhat implicit.
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 the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it streams progress and returns a result, but lacks detail on whether it modifies the flow in place or creates a new version, and any required permissions. More context would strengthen this dimension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, consisting of two sentences that cover when to use, what it does, and what to expect (streaming progress, final result). No 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 tool with three well-described parameters and no output schema, the description provides adequate context: it covers the core behavior and streaming. It could briefly explain what 'refine' typically involves or what the output looks like, but overall it suffices.
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 covers all parameters with descriptions (100% coverage). The description adds minimal extra semantics beyond the schema, such as implying natural language input. Given high schema coverage, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: refine or rebuild an existing CloudFlow automation using natural language. It differentiates from siblings like 'trigger_cloud_flow' by focusing on modification rather than execution. However, it could be more precise about what 'refine' vs 'rebuild' entails.
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 indicates when to use the tool ('when the user wants to refine or rebuild'), but it does not provide explicit guidance on when not to use it or suggest alternative tools. For example, it does not mention that 'trigger_cloud_flow' is for executing flows or that 'ask_ava' tools are for general queries.
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 destructiveHint annotation, the description discloses idempotent behavior for already-terminal operations, a 404 for nonexistent or cross-tenant operationIds, and a dryRun mode that performs validation without modifying state. This is strong behavioral context that helps an agent predict 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The cancellation behavior, idempotence, 404 condition, and dryRun guidance are concise and useful. The first sentence about managing reports and getting JSON data is unrelated boilerplate that does not earn its place and adds confusion.
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 important behavioral details and error conditions, which is good for a destructive async-cancellation tool. However, it omits explanation of the required Idempotency-Key, does not describe the response format, and does not mention the customerContext scoping rule that the schema only partially covers.
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 adds meaning for dryRun (validate without state changes) and operationId (the operation to cancel), but it does not explain the required Idempotency-Key parameter at all. With schema coverage at only 25%, this leaves a key parameter under-documented; customerContext is described only in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The core sentence 'Cancels a pending or running async report operation' clearly identifies a specific verb and resource, and distinguishes it from sibling operations like get_async_operation or get_async_operation_results. However, the opening sentence about managing reports and getting JSON data is generic and could mislead an agent about what this tool actually does.
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 makes it clear this tool is for canceling pending or running async operations, and mentions dryRun for validation. However, it does not explicitly contrast it with alternatives such as get_async_operation or get_async_operation_results, nor does it state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations: latency (up to 15 minutes), file format constraints (CSV, ZIP, GZ), and max file size (30 MB). It does not contradict annotations. The destructive hint is appropriately supported by the 'Ingest' action. However, it does not clarify authorization needs or what exactly gets modified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. No wasted words. The first sentence covers the core action, and the second adds essential constraints and latency info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description does not mention what the response or return value is (e.g., success confirmation). It covers the main use case, constraints, and latency, but lacks details on error handling or result format. Given the simplicity, it's adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters. The description adds no new information about parameter semantics beyond what's in the schema. According to the rule, baseline is 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ingests third-party data via CSV file. The verb 'Ingest' and 'Sends' with resource 'events to DataHub' are specific. However, it does not explicitly differentiate from its sibling 'send_datahub_events', which likely serves a similar purpose but perhaps with different input format.
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 sending batch CSV data but provides no explicit guidance on when to use this tool versus alternatives like 'send_datahub_events' or 'delete_datahub_events_by_filter'. It mentions a latency of 15 minutes but no exclusions or prerequisites.
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?
Adds behavioral context beyond the annotations: specifies that it removes the insight and all associated resource results. Annotations already indicate destructiveness, but description enriches with scope of deletion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Contains a generic first sentence that adds little value. The core action and alternative are clear, but the description could be more direct without the introductory phrase.
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?
Missing important context: no mention of what 'batch source' is, no sourceID parameter, no details on idempotency, errors, or return values. For a destructive operation with no output schema, more completeness is needed.
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?
With 50% schema coverage and no description for insightKey, the description fails to add meaning beyond the schema. Only customerContext is described in schema, not in description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes all insights matching a key from the batch source, and distinguishes from the sibling tool delete_insight_result by mentioning single-insight deletion alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use the alternative endpoint for single-insight deletion, implying this is for batch deletion, but does not elaborate on when to avoid using this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of disclosing behavior. It only states 'returns details' without specifying whether this is a read-only operation, what happens if the ID is invalid, or any side effects. This is insufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential information without any extraneous words. It is front-loaded with the main action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is minimally viable but lacks details about return format, error cases, or any additional context. For a more complete description, it could mention response structure or typical usage notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the 'id' parameter as 'The numeric ID of the support ticket to retrieve,' achieving 100% coverage. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns details of a specific support ticket by its ID. It distinguishes from sibling tools like 'list_tickets' (which returns many) and 'create_ticket' (which creates a new one), leaving no ambiguity about the function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need details of a single ticket via its ID) and implicitly differentiates from 'list_tickets' and 'create_ticket'. However, it does not explicitly state when not to use it or mention any prerequisites, but the context makes the usage 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 and destructiveHint=false, so the tool's safety profile is clear. The description adds useful context that Cloud Diagrams visualize infrastructure, and states the return behavior (list of snapshots). No contradictions. It could mention pagination or ordering, but the annotations and description together provide adequate transparency for a non-destructive read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence provides background context, which is somewhat tangential but not harmful. The second sentence directly states the function. It is front-loaded with the main action. Could be slightly more efficient by removing the first sentence, but it is still well-structured.
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 (list snapshots for a layer) and the absence of an output schema, the description gives a basic understanding but lacks details on pagination (limit, offset), ordering (sort), and what information the snapshot list contains. For a list operation with multiple parameters, it is minimally complete but could be more informative.
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 only 20% (only customerContext has a description). The tool has 5 parameters, but the description only implicitly ties 'id' to the diagram layer. There is no explanation for sort, limit, offset, or how they affect the result. With low coverage, the description should compensate by detailing the parameters, but it 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 that the tool returns a list of saved snapshots for a specified diagram layer. It uses a specific verb ('Returns') and resource ('list of saved snapshots'), and the reference to 'specified diagram layer' distinguishes it from sibling tools like get_cloud_diagram_layer_snapshot (singular) and other cloud diagram manipulation 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 does not provide explicit guidance on when to use this tool versus alternatives. It implies usage for listing snapshots but offers no context about prerequisites, when not to use it, or comparisons to siblings like get_cloud_diagram_layer_snapshot or export_cloud_diagram_json. The presence of many sibling tools makes this lack of guidance noticeable.
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 annotations (destructiveHint=true, not read-only), the description explains that existing unresolved results are removed and that server-computed fields are returned. This adds valuable context about 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences with no filler. The first sentence effectively states the purpose. Slight improvement possible by adding bullet points for clarity.
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 complex tool with 5 parameters and no output schema, the description covers the core behavior (replacement, deletion) and mentions response details. Missing prerequisites or error conditions, but overall adequate.
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 does not elaborate on individual parameters beyond what the input schema provides. With 40% schema coverage, the description could add more meaning, but it mentions the server-computed fields in the response, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool replaces all resource results for an insight, using specific verbs like 'Replaces' and 'remove'. It distinguishes from similar tools like post_insight_result by describing bulk replacement, but does not explicitly name sibling alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for bulk replacement and provides a specific case for deletion (empty array). However, no explicit when-to-use vs alternatives like post_insight_results or delete_insight_result is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states this tool finalizes a pending write action including 'deleting a resource,' which is inherently destructive, yet the annotations declare destructiveHint=false. This is an annotation contradiction. The extra details about user confirmation and token expiry are useful but cannot overcome the 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?
Two sentences with no redundant filler, front-loaded main purpose (what it finalizes) before usage conditions. 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 single-parameter confirmation tool, the description covers the call condition, negative condition, and token handling. No output schema is present, but return value descriptions are not essential for correct invocation here; still, a mention of expected response could make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the schema already documents 'token' with exactness requirements. The description repeats 'Pass the token exactly as it was returned,' adding no new semantics beyond the schema, so it stays at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('finalizes') and a specific resource ('a pending write action ... previously staged by another tool'). It distinguishes this from all sibling read/write tools by clarifying it is the confirmation step, not the operation itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call ('only after the user has explicitly confirmed the action summary') and when not to ('If the user declined, do not call this tool'), including the fallback behavior (token expires automatically).
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 the tool as readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the description does not need to restate those. It adds useful behavioral context about ownership and permission requirements, but it does not explain what destructive side effects may occur when creating a region or whether it can overwrite/replace existing configurations.
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 efficient, three sentences with no filler. It opens with the overall purpose, quickly narrows to the specific creation action, and then lists the critical constraints. Every sentence contributes useful 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 description provides key constraints and permission requirements, but leaves gaps around parameter details, side effects, and the meaning of a custom region in the broader geographic access model. It is adequate for basic invocation but not fully complete for an agent that has no other context, especially given the low schema description coverage and the absent output schema.
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 only 25%, with only customerContext described. The description does not clarify the meaning of name, countryCodes, or X-Tenant-Id. It provides high-level context about country-based access and tenant ownership, but does not compensate for the lack of parameter-level documentation 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 states a clear action ('Creates a custom region') with a specific resource ('custom region owned by the authenticated tenant'). It also provides meaningful context ('country-based access to tenants in your customer hierarchy') that distinguishes it from the many get/list/update/delete geographic access sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit prerequisites: the tenant must be a customer-hierarchy root and the caller must have the UsersManager permission. It does not explicitly state when to use this tool versus alternatives, but the creation purpose and conditions are clear enough for an agent to select it appropriately.
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 adds useful behavioral detail beyond the readOnly/destructive annotations by specifying the response scope (IAM status/diff and timestamps) and explicitly excluding tenant fan-out, handshake aggregation, and pagination. The word 'Manage' slightly muddies the read-only nature, but it does not directly 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The second sentence is dense and informative, but the first sentence leads with a broad 'Manage AWS billing-transfer mappings' phrase that is not the actual operation and partially duplicates the listing concept. A tighter structure would lead directly with the status-return behavior and then list the exclusions.
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 absence of an output schema, the description still covers what the response contains, who can call the tool, and which expensive behaviors it deliberately omits. It does not explain what IAM status/diff means exactly, but for a polling tool with simple parameters this is a reasonably complete contract.
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?
customerContext is well documented in the schema with clear rules about when it is required and when to omit it, but X-Tenant-Id has no schema description and the tool description adds no parameter guidance. With 50% schema coverage, this is minimally viable but relies on the agent inferring the tenant-header semantics.
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 second sentence clearly identifies the tool as a read-only status operation: it returns each caller's PMAs with only IAM status/diff and timestamps. It distinguishes itself from the related billing-transfer list tools by framing itself as a lightweight polling surface and calling out absent aggregation/pagination, though the opening 'Manage AWS billing-transfer mappings' phrase is overly broad for a get-status tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool as a 'lightweight polling surface for the onboarding wizard' and states that it is distributor-only, giving clear context for when it should be used. It does not explicitly name alternative tools or say when not to use it, but the onboarding-wizard signal is a solid usage guideline.
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 meaningful behavior beyond that: the hierarchy-root authentication requirement, the constraint that only root/child targets are valid, and the notable disclosure that targets outside the hierarchy are 'returned as not found' rather than as errors. The UsersManager permission requirement is also valuable. 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?
Four sentences with the core purpose front-loaded in the second sentence and the prerequisite/behavior details packed efficiently after it. The opening sentence 'Manage country-based access to tenants in your customer hierarchy' is a slightly redundant umbrella over the tool name, but it does add domain context that helps differentiate from unrelated sibling tools.
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 prerequisites, hierarchy constraints, permission requirements, and not-found error behavior, which is strong for a simple get-by-id tool. However, with no output schema, the return shape of 'the geographic scope' is never defined (e.g., allowed countries, custom regions), leaving the agent uncertain about what the response contains.
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 only 33% (customerContext is described; targetCustomerId and X-Tenant-Id are not). The description partially compensates by implying targetCustomerId must be a root or child customer and that X-Tenant-Id should identify the hierarchy-root tenant, but it doesn't fully clarify parameter formats or how targetCustomerId relates to customerContext.
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: 'Returns the geographic scope for a target customer.' This clearly distinguishes it from the update/delete customer-scope siblings and the user-scope sibling by the 'get' action and customer focus. The opening sentence 'Manage country-based access to tenants' is a broader umbrella that slightly dilutes precision, preventing 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear applicability conditions: the authenticated tenant must be the hierarchy root, the target must be the root or a child customer, and the UsersManager permission is required. It does not explicitly name alternatives or exclusion conditions (e.g., 'for user-level scope use get_user_geographic_access_scope'), so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and destructiveHint=false; the description adds genuine behavioral context beyond them: out-of-hierarchy targets are 'returned as not found' rather than causing an error, and root-tenant authentication is required. The 'Returns' statement matches readOnlyHint=true, so 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no filler; the constraints and permission are packed efficiently. The first sentence 'Manage country-based access...' is a category label that adds little value and mildly clashes with the read-only nature of the tool, which keeps this below 5.
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 permissions, hierarchy requirements, and not-found behavior, which is solid for a simple read. However, there is no output schema, and the description never hints at what the returned 'geographic scope' contains (e.g., country codes vs custom regions), leaving the agent to guess the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate. It does clarify the relationship between userId and targetCustomerId (the user belongs to the target customer) and constrains targetCustomerId to the hierarchy. However, X-Tenant-Id is left unexplained and no format guidance is given for the two required ID parameters.
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 clear action and resource: 'Returns the geographic scope assigned to a user who belongs to the target customer.' This distinguishes it from the sibling get_customer_geographic_access_scope (user-level vs customer-level scope). The opening word 'Manage' is slightly misleading for a read-only tool and prevents 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete applicability constraints: the authenticated tenant must be the hierarchy root, the target must be within that hierarchy, and the UsersManager permission is required. It does not explicitly name alternatives or say when to prefer a sibling tool, so it stops short of 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 indicate destructiveHint=true, and the description adds that the tool is destructive ('Deletes a connection') and provides specific behavior: returns 409 if the connection is referenced by one or more flows. This adds value beyond annotations by disclosing a conflict scenario.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. It front-loads the purpose and provides a key behavioral detail without any fluff. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (delete operation with two parameters), the description is sufficiently complete. It covers the resource type, action, and a relevant error condition. No output schema exists, so return details are not needed. Minor missing context on success response, but acceptable.
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 coverage is 50% (only customerContext has a description). The description does not mention either parameter or add meaning beyond the schema. For a tool with low schema coverage, the description should compensate but fails to do so.
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 'Deletes a connection' on a specific resource 'cloud provider connections used in CloudFlow workflows (AWS and GCP)'. It distinguishes from siblings like create_cloudflow_connection and update_cloudflow_connection by specifying the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to delete a connection) but does not explicitly state usage context or when alternatives (e.g., update or list) are more appropriate. It mentions a 409 error if referenced, which provides some guidance on a constraint, but lacks explicit when-to-use or when-not-to-use 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?
Annotations already indicate destructive behavior. Description adds the permanence of deletion and the scope (associated results) and the public API restriction. No contradiction. Provides useful context beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: context, action, constraint. No superfluous text. Front-loaded with key 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 destructive action with annotations, the description covers key aspects (permanence, scope, constraint). Could mention authorization or failure behavior but overall 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?
Schema coverage is low (33%). The description indirectly explains sourceID via the public API constraint but does not describe insightKey or customerContext. Without description, agent must infer from 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?
Description clearly states it permanently deletes a single insight and associated resource results. It differentiates from sibling 'delete_insight_results' by specifying 'single insight' and adds a constraint (only public API insights).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for single insight deletion and mentions the public API constraint, but does not explicitly compare to 'delete_insight_results' (plural) or provide alternative guidance. No 'when not to use' 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 mark the operation as read-only and non-destructive. The description goes beyond that by explaining the pagination contract in detail: pass the returned pageToken back as a parameter and stop when no pageToken is present. It also clarifies the default behavior when filters are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The substantive sentences are tight and useful, but the first sentence about evaluating commitments and planning purchases is marketing fluff that does not describe this endpoint's behavior and could even mislead an agent. With that sentence removed, the description would be nearly ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, paginated list endpoint with no output schema, the description covers the purpose, filter options, default behavior, and pagination stop condition. It does not cover alternative selection or a few parameter details, but an agent has enough information 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?
Schema description coverage is only 10%, so the description carries real weight here. It names the filterable parameters (state, instance type, instance family, region, offering class) and explains pageToken semantics. It does not explain X-Tenant-Id or maxResults, but those are either self-describing or peripheral given the schema 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 core statement 'Returns a paginated list of Reserved Instances (RIs) for the specified AWS organization' clearly identifies the verb, resource, and scope. However, the opening marketing sentence about evaluating commitments and automating purchases is broader and not specific to this tool, and no explicit differentiation from sibling tools like list_aws_savings_plans is provided.
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 actionable context: use this endpoint to list RIs for an AWS organization, optionally filtering by several dimensions, and omit filters to get all RIs. It does not explicitly mention when not to use it or name alternatives such as list_aws_savings_plans or list_aws_recommendations.
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 state-changing behavior ('Marks the suggestion as accepted and links it to an existing budget') and adds the prerequisite/ownership constraint. However, with destructiveHint=true in annotations, it does not clarify whether accepting is irreversible or what happens to the suggestion after acceptance, so some behavioral context is still missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the core purpose, followed by the mechanism and prerequisite. It contains no redundant fluff and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity action tool with 4 parameters, no output schema, and destructive annotation, the description covers the purpose, state change, prerequisite ordering, and an account ownership constraint. It could additionally mention response behavior or explicitly contrast with dismiss_budget_suggestion, but it is sufficiently complete for correct 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 schema already describes budgetId, customerContext, and editedBeforeAccept (75% coverage). The description adds useful relational context for budgetId by explaining the prerequisite and that the budget must belong to your account. However, the `id` parameter is not explicitly defined in either the schema or the description, relying on the tool name and context.
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 ('accept') and resource ('budget suggestion'), and clearly distinguishes this from sibling tools by stating that it 'Marks the suggestion as accepted and links it to an existing budget.' This differentiates it from dismiss_budget_suggestion and list_budget_suggestions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: create the budget first via `POST /analytics/v1/budgets`, then pass its id as `budgetId`. It also notes the budget must belong to your account. It does not explicitly name an alternative tool for dismissing suggestions, but 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behavior beyond the annotations: immediate 202 response, Location header pointing to status, required Idempotency-Key for at-most-once submission, deduplication returning the existing in-flight operation, and dry-run validation. This is especially valuable given the annotations only convey read/write/open-world flags and the tool has a side-effecting async workflow.
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, moving from the operation to response behavior to required header to deduplication and dry-run validation. The first sentence is broad and somewhat generic, but every later sentence adds concrete, 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?
Given the complexity of the tool and the absence of an output schema, the description adequately covers invocation, required header, duplicate behavior, and dry-run mode. It intentionally leaves polling/result retrieval to sibling tools like get_async_operation and get_async_operation_results, which is a reasonable boundary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50%, but the description adds important semantic meaning to Idempotency-Key (at-most-once deduplication) and dryRun (validate without creating an operation), which the schema itself does not explain. The config and customerContext parameters are already reasonably described in the schema, so the description compensates for the gaps where it matters most.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation: submitting an async report execution job using an inline configuration and receiving a 202 with a Location header. It distinguishes from async_run_report_by_id by emphasizing 'inline configuration', though it never names the sibling or states the contrast explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides useful context: use for async submissions with inline configs, and use ?dryRun=true to validate without creating an operation. However, it gives no explicit guidance on when to prefer this tool over async_run_report_by_id or any other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this as destructive and non-read-only; the description adds the key side effect that a normal call creates an operation, while dryRun avoids it. It also discloses the immediate 202, Location header, and required Idempotency-Key header—information not present in the annotations. It does not mention downstream result retrieval or potential cost, but it is substantially transparent.
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: the operation is stated in the second sentence, followed by response shape, idempotency requirement, and dryRun behavior. The first 'Manage Cloud Analytics reports and get reports data in JSON format' sentence is somewhat generic and could be trimmed, but the rest earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the essentials for invoking the tool: required header, dryRun validation, async creation, and the Location header. But because there is no output schema, the description should also point toward polling or result retrieval via the async operation endpoints, and it does not clarify the date/timeRange override parameters. The destructive annotation also makes it worth explaining more about what executing a report entails.
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 adds meaning beyond the bare schema for the central parameters: id is the saved report identifier, Idempotency-Key is a required header, and dryRun validates without creating an operation. However, with schema description coverage at only 14%, the startDate, endDate, and timeRange parameters remain unexplained in both schema and description, leaving a real gap for optional date-range control.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete operation—submitting an async execution job for a saved report by ID—and states the immediate 202 response with Location header. This distinguishes it from related report tools like get_report_results, async_run_inline, and run_query. The opening sentence is broad, but the specific clauses carry the meaning.
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: use this tool when you need to execute a saved Cloud Analytics report asynchronously, and use dryRun=true to validate without side effects. It also makes the Idempotency-Key prerequisite explicit. It does not name alternative tools or explicitly say when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 useful detail by specifying that the scope is cleared and left unassigned, that the operation is idempotent, and that specific hierarchy and permission conditions must hold. This goes beyond the annotation signals without contradicting them.
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 each sentence adds useful information: context, action, hierarchy prerequisites, idempotency, and permission. The opening 'Manage country-based access...' sentence is somewhat broad, but it is not redundant and the rest is tightly 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 destructive tool with no output schema, the description adequately covers the effect, preconditions, idempotency, and required permission. It does not elaborate on tenant-header parameters, but the schema already documents customerContext and the core invocation requirements are 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?
Schema description coverage is only 25%, so the description needed to compensate, but it only indirectly addresses targetCustomerId and userId through 'target customer' and 'user'. It does not explain X-Tenant-Id or fully clarify how the authenticated-tenant constraint maps to parameters, leaving significant param semantics undocumented.
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 ('Clears') and resource ('geographic scope assigned to a user'), which clearly distinguishes this tool from sibling delete tools like delete_customer_geographic_access_scope. The sentence 'leaving it unassigned' clarifies the resulting state, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context by stating that the authenticated tenant must be the hierarchy root, the target must be the root or a child customer, and the UsersManager permission is required. It does not explicitly name alternatives or when-not conditions, but the constraints make intended invocation clear.
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?
Even with readOnlyHint=true and destructiveHint=false already present, the description adds substantial behavioral context: transitive subflow inclusion, tenant-neutral/credential-free output, rebinding of tenant-scoped references as named requirements, unsupported policy/Slack references, and explicit exclusions (credentials, tenant IDs, schedules, execution state). This goes far 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 opening 'Manage CloudFlow.' is generic filler, but the remaining three sentences are information-dense and logically organized: what is serialized, how tenant references are handled, and what is excluded. The length is justified by the tool's complexity.
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 is largely complete for a read-only export tool given no output schema: it specifies output type, portability constraints, and limitations. The main gap is the undocumented includeVariableValues parameter, and the description does not state how the bundle is returned or what happens on missing flows, but these are secondary.
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 coverage is only 33%, and the description does not explain includeVariableValues or clarify the exact meaning/format of flowId. It provides only an indirect hint that 'flow' refers to flowId. The description does not compensate for the undocumented parameters, leaving a meaningful gap for agents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation (serializes a CloudFlow flow plus referenced subflows) and a concrete output (a tenant-neutral, credential-free JSON bundle). It distinguishes the tool from its import sibling by explicitly mentioning the import operation as the counterpart, and from list/management tools by focusing on export/transfer behavior.
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 makes the purpose clear and references the import operation, which implies a migration/backup use case, but it never explicitly states when to use this tool instead of alternatives such as list_cloudflows, build_cloud_flow, or export_cloud_diagram_json. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds context about returned details but does not disclose additional behavioral traits beyond what annotations provide. 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?
Two sentences, front-loaded with purpose and constraint, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter, the description outlines return details adequately. However, it does not mention any prerequisites (e.g., that the AWS account must be connected to DoiT) which could be inferred but is not explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with a good description and example for accountID. The description reiterates the requirement but adds no new semantic info beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves CloudConnect details for a specific AWS account, listing example details (IAM role ARN, billing S3 bucket, features) and explicitly distinguishes from Google Cloud/Azure accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('use this when user wants CloudConnect details') and provides a negative instruction ('Do NOT use for Google Cloud or Azure accounts'), but does not mention specific sibling tools as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows it is safe. The description adds return value details (anchor + related with type and distance) but does not discuss authorization or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: first states purpose and output, second lists requirements and negative guidance. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately describes the return structure (anchor + related with type and distance). Could mention error conditions or pagination but sufficient for a query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description only repeats required parameters (layerId, resourceId) without adding new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: understanding how a specific resource connects to others in a cloud diagram, listing upstream/downstream edges and group membership. It explicitly differentiates from cost-analysis tools by naming alternatives.
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 when-to-use context ('when the user wants to understand...connected to other resources') and negative guidance for cost analysis. However, does not exclude other diagram tools like get_cloud_diagram_components.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes the retrieval operation but does not mention whether it is read-only, any authentication requirements, or potential side effects. The description is adequate for a simple read tool but lacks explicit 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?
Two sentences: first states the core purpose, second details the returned data. Every sentence is essential and well-structured 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 1-parameter retrieval tool with no output schema, the description adequately explains the return content (commitment periods, values, spend attainment). It is nearly complete, though it could mention if the return is paginated or if there are limits, but given simplicity, it's 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 100% coverage for the 'id' parameter. The description adds meaning by explaining what the commitment is (EDP) and what details are returned, helping the agent understand the parameter's purpose beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns details of a specific EDP commitment contract by ID, including full breakdown of commitment periods, contracted values, and spend attainment. This verb+resource+scope is specific and distinguishes it from list_commitments which lists commitments.
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 when/when-not or alternatives are mentioned. Usage is implied: use when you have a commitment ID and need details. No guidance on when to use this versus list_commitments or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses role-based access (public vs private) but lacks details on ordering, pagination, or output structure. This is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence fronts the purpose, and the second adds critical role-based detail. It is optimally concise for the information conveyed.
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 one required parameter and no output schema, the description covers the essential behavior (role-based filtering). Missing are details on output structure and ordering, but given low complexity, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'ticketId' is described in the schema as 'The numeric ID of the support ticket whose comments to retrieve.' With 100% schema coverage, the description adds no further meaning beyond what the schema provides, consistent with the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Returns all comments on a support ticket' with a specific verb and resource. It distinguishes from sibling tools like list_tickets and get_ticket by focusing on comments, and adds role-based behavior (public vs private) that adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool and notes access differences for customers vs employees. However, it does not explicitly state when not to use it or compare to alternatives like get_ticket or create_ticket_comment.
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=true, so the write/destructive nature is covered. The description adds that the operation is a batch create/update and that insights include metadata and resource results inline. However, it does not disclose upsert semantics, key-based identity, or that immutable fields are silently ignored, which are important behavioral details left to the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences that front-load the core batch operation, then explain the inline structure and point to alternatives. The opening sentence 'Manage cloud insights...' is slightly generic but not wasteful, and the overall structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential batch aspect, inline resource results, and alternative endpoints. However, it omits customerContext scoping requirements and the upsert/overwrite mechanism, leaving important operational nuances to the schema and annotations. For such a complex tool, 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 coverage is 100%: both top-level parameters (results, customerContext) and nested properties have detailed descriptions. The description itself does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core action: 'Creates or updates multiple insights in a single batch request.' This is a specific verb+object+mode that distinguishes the batch tool from the singular post_insight_result and post_insight_resource_results siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides a when-not-to-use condition: 'For granular control over insight metadata and resource results independently, use the single-insight and resource-results endpoints instead.' This names the alternative endpoints, giving the agent clear decision 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?
Beyond annotations, the description discloses invalidation of previous token, reactivation of cancelled invites, and the required 'usersManager' permission. This adds 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured in three short paragraphs, each addressing a key aspect: action, error case, and permission. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the action, error, and permissions, it lacks details on success response and other potential error codes. Given no output schema, more completeness would be beneficial.
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 coverage is only 25%, with only one parameter described. The tool description mentions the 'id' parameter implicitly but does not explain 'dryRun' or 'Idempotency-Key', leaving gaps in understanding parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action: resetting invite expiry, invalidating previous token, and triggering a new email. It distinguishes from siblings like 'invite_user' and 'cancel_invite' by detailing the effect on cancelled invites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains applicability to any invite state, including cancelled, and mentions a 404 error for missing invites. However, it does not explicitly contrast with alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=false, destructveHint=true), so the bar is lower. The description adds genuinely useful context beyond annotations: the UsersManager permission requirement and the ownership scoping to the authenticated tenant. The phrase 'Manage country-based access to tenants' hints at the broader side effects implied by openWorldHint=true, though it does not detail what destructive consequences may occur when countries are removed.
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?
Three short sentences, each earning its place: domain context, primary function, and permission prerequisite. The main action is front-loaded in the second sentence. The first sentence is slightly broad ('Manage...') but adds useful business-domain framing, so the structure remains tight with no redundant 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?
For a 5-parameter mutation tool with no output schema and destructiveHint=true, the description covers the essentials: what is updated, ownership, and permission. But it leaves meaningful gaps — whether updating one field preserves the other (partial update vs full replace), the role of the X-Tenant-Id header, and what destructive side effects (e.g., revoking tenant access) may occur. These gaps matter for an agent deciding how to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 20%, the description must compensate. It does partially: 'name, country membership, or both' maps meaningfully to the name and countryCodes fields, telling the agent these are the updatable properties — value the bare schema types do not provide. However, X-Tenant-Id is left undocumented by both schema and description, and customRegionId's role is only implied rather than stated, so compensation is 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 states a specific verb and resource: 'Updates the name, country membership, or both for a custom region.' The opening phrase 'Manage country-based access to tenants in your customer hierarchy' gives valuable domain context. It distinguishes from sibling tools like get/delete/create_geographic_access_custom_region and the customer/user scope tools by specifying exactly which entity is being modified.
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 for when to use this tool: when an existing custom region's name or country membership needs modification. It also states the prerequisite ('Requires the UsersManager permission') and an ownership constraint ('owned by the authenticated tenant'), which helps an agent avoid misuse. However, it does not explicitly name alternatives or state when-not-to-use (e.g., use create_geographic_access_custom_region for new regions), 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and openWorldHint=true, covering mutation and side effects. The description adds the confirmation requirement but does not elaborate on permissions, error states, or operation details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each serving a purpose: usage context, confirmation guideline, and exclusion of sibling tools. Front-loaded with purpose, 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?
Describes operation and provides usage guidance, but lacks information about return values, success/error responses, or behavior of simultaneous add and remove. Given no output schema, the agent may need more context on expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the parameters. The description adds no additional semantic value beyond stating 'assign or unassign cloud resources' – no extra detail on add/remove arrays or object 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?
Clear verb+resource: 'assign or unassign cloud resources to a label'. Explicitly distinguishes from sibling tools create_label and get_label_assignments, leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (user wants assign/unassign) and when not to (creating labels or viewing assignments), naming alternative tools. Also advises to ask user confirmation before executing.
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 destructiveHint=true, so the description adds value by instructing to confirm parameters before execution. However, it does not elaborate on what exactly is destroyed or other behavioral traits like necessary permissions or side effects, leaving some 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 concise, with three sentences that front-load the purpose and provide clear boundaries. No extraneous information, every sentence is valuable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, mutually exclusive rule vs. rules), the description is too brief. It does not explain the structure of rules or guide on choosing between 'rule' and 'rules'. The schema helps, but more context is needed for full agent comprehension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond the schema; it only generically mentions 'allocation parameters' without deepening understanding of the rich nested structures.
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 is for creating a new cost allocation rule, using a specific verb and resource. It also distinguishes it from sibling tools like list_allocations (viewing) and create_label (labels), avoiding ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (user wants to create a new allocation rule), when not to use (viewing existing allocations or creating labels), and provides alternatives. Also instructs to ask user for confirmation before executing, setting clear usage expectations.
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 destructive and non-read-only behavior. The description confirms creation but does not add details beyond that. It includes a confirmation step but omits information about permissions, side effects, or that the tool can create alerts within the budget. The open world hint suggests additional unspecified behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three sentences, front-loading the purpose, then required parameters, then usage guidelines and exclusions. Every sentence serves a clear purpose with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (19 parameters, including nested objects), the description is somewhat minimal. It doesn't explain that alerts can be created within the budget, nor does it describe the return value. However, it does distinguish from create_alert and provides basic context. The absence of an output schema is partially mitigated by the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to add much parameter information. The description briefly mentions required parameters but does not elaborate on optional ones like alerts or collaborators. This is adequate given the schema already explains each parameter in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new cloud budget with spending limits and alert thresholds. It specifies required parameters and explicitly distinguishes from sibling tools like list_budgets, get_budget, and create_alert, ensuring the agent knows when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: use when the user wants to create a budget, and it lists what not to use (viewing or alert creation) with alternative tools. It also instructs the agent to ask the user to confirm parameters before executing, which is a clear usage guideline.
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 destructiveHint=true and readOnlyHint=false. The description adds the important behavioral trait that user confirmation is required before execution, providing context beyond the annotations. 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 two sentences long: the first states the purpose, the second provides usage guidance and exclusions. It is front-loaded and every sentence is necessary 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?
Despite the nested object parameters and lack of output schema, the description covers when to use, confirmation requirement, and exclusions. It is adequate for a simple creation tool but could mention response or validation behavior. Still, it is sufficiently complete for the task.
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 does not describe any parameters. The input schema has a nested object with 6 required properties, each with descriptions, but the description adds no meaning beyond the schema. With 0% schema description coverage, 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 creates a new support ticket and explicitly distinguishes it from viewing tickets (list_tickets) and cloud incidents (get_cloud_incidents). 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (user wants to create a new support ticket) and when-not-to-use (viewing existing tickets, cloud incidents) with sibling tool names. It also instructs to ask the user to confirm details before executing.
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 destructiveHint=true. The description adds that nested folders will be deleted and reports/allocations are moved to root, going beyond annotations. It does not discuss permissions or reversibility, but the destructive behavior is clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: one for context, one for the action, and one for consequences. It is efficient and front-loaded with the core 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?
The description covers what the tool does and its key side effects for a destructive operation without output schema. It does not specify error conditions or permission requirements, but the core behavior is sufficiently explained.
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 input schema has two parameters: 'id' (required, no description) and 'customerContext' (with description). Schema description coverage is 50%. The description does not mention either parameter, so it adds no value beyond the schema for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a folder, and distinguishes it from sibling tools like create_folder or update_folder by specifying the deletion effect and consequences (nested folders deleted, contents moved to root).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what happens when the tool is used (nested folders deleted, reports/allocations moved to root), providing clear context. It does not explicitly state when not to use it or mention alternatives, but the effect is well-described.
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 destructive behavior, and the description adds important behavioral constraints beyond that: ownership by the authenticated tenant, the inability to delete assigned regions, and the permission requirement. No contradiction with the readOnlyHint/destructiveHint 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?
Four short sentences, each adding a distinct piece of information: domain context, action, constraint, and permission. The description is front-loaded and has no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with one required parameter and no output schema, the description covers the critical operational constraints: ownership, assignment state, and required permission. It does not mention return behavior or error cases, but these are less critical given the destructive annotation and the simplicity of the 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?
Schema description coverage is only 33%, and the tool description does not compensate. The required customRegionId is not explicitly described as the target region identifier, and X-Tenant-Id is left entirely unexplained. Only customerContext benefits from a schema-level description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a custom region, naming the specific resource and action. It also distinguishes itself from sibling create/update/list tools by emphasizing deletion and the ownership/assignment constraints.
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 conditions for use: the region must be owned by the authenticated tenant, cannot be assigned, and requires the UsersManager permission. It does not explicitly name alternative tools for other operations, but the context is sufficient for an agent to choose this over similar geographic access tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description bears full responsibility for behavioral disclosure. It clearly indicates a read operation with no side effects and details the return structure (name, type, nested config with data source, metrics, etc.). However, it does not mention any authentication requirements or rate limits, though for a read-only tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence front-loads the verb and resource, and the second sentence adds valuable return structure details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter (one string ID) and no output schema, the description is complete. It explains what the tool does, the expected input, and the structure of the return value. No further details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single parameter 'id' with 100% schema description coverage (schema has its own description). The tool description does not add additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'Get' and the resource 'configuration of a specific Cloud Analytics report by ID'. It distinguishes from sibling tools like list_reports (which lists all reports) and get_report_results (which returns results), 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a report ID, but it does not explicitly state when to use this tool versus alternatives like list_reports or get_report_results. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses permission requirements and tenant scoping. It mentions 'Read access requires...' which aligns with the readOnlyHint annotation. The initial phrase 'List and manage' could imply write capabilities, but the rest of the description clarifies it is a listing operation, so no contradiction exists. It adds useful context beyond annotations about who can call and token scope.
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 reasonably concise, consisting of four sentences covering purpose, scope, permissions, and token requirements. It is front-loaded with the main action. The phrase 'List and manage' is slightly redundant since it only lists, but overall the structure is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with readOnlyHint and no output schema, the description covers the essential context: what it does, who can use it, and permission requirements. It doesn't mention pagination or sorting, but these are not required for completeness given the tool's simplicity and the annotations provide safety assurances.
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 50% (only customerContext has a description in the schema). The tool description adds minimal parameter meaning: it mentions 'specified customer' but doesn't explain the distinction between customerID and customerContext. The schema already covers customerContext well, and customerID is self-evident, so the description provides little additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Lists the contracts held by the specified customer', with a specific verb and resource. It distinguishes from siblings like get_contract (which retrieves a single contract) by indicating this is a listing operation scoped to a customer.
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 concrete guidance on when the tool is callable: by T1/T2 PartnerOps principal for their own tenant or descendant tenants. It also specifies permission requirements (contractsReadOnly, contractsViewer, or write-capable role). While it doesn't explicitly name alternatives, the scoping and permission context make usage 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 indicate read-only, open-world, non-destructive behavior. The description adds meaningful context by specifying authorization requirements (ContractTemplatesAdmin, DoiT API access, entitlement) and tenant ownership, which is valuable beyond the annotations. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences) and provides high-signal information about scope and permissions. The opening 'Manage' is broader than the actual list operation, but the second sentence immediately corrects it, so there is minimal waste.
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 listing tool with one optional parameter, the description includes ownership scope, auth requirements, and PartnerOps context. It does not detail return structure or pagination, but those are not required for a list endpoint and no output schema is specified.
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 for the single customerContext parameter is 100%, so the structured schema already explains the parameter. The tool description adds no additional parameter-specific semantic detail, hence the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Lists contract templates'), the resource ('contract templates'), and the ownership scope ('owned by the authenticated tenant from the bearer token'). It also distinguishes from siblings like get_contract_template by emphasizing the plural listing and tenant scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: which templates are returned (owned by the authenticated tenant) and the required permissions. It does not explicitly state when to use this instead of get_contract_template or list_contracts, but the tenant-scoped listing semantics make the intended use clear.
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?
Annotations already mark destructiveHint=true and readOnlyHint=false, but the description goes well beyond them by disclosing atomic replacement, idempotency for identical requests, hierarchy-root constraints, and the UsersManager permission requirement. This adds substantial behavioral context that annotations cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, each contributing a distinct piece of information: purpose/behavior, atomicity, hierarchy and tenant preconditions, and permission requirement. There is no filler, and the most important 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 prerequisites, idempotency, and permissions well, but there is no output schema and the description does not mention return values or how the new geographic scope should be expressed in the request. Since the schema itself also does not document a scope/country parameter, this is a meaningful gap for an agent trying to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, so the description must compensate for undocumented parameters. It adds meaning for targetCustomerId (the target root or child customer) and userId (the user belonging to that customer), but it does not clarify X-Tenant-Id or how the actual replacement scope is supplied in the request. The compensation is partial and leaves key request data unexplained.
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 a specific operation: atomically replacing the geographic scope assigned to a user. The resource is identifiable ('geographic scope assigned to a user who belongs to the target customer'), and the verb 'replaces' distinguishes it from get/delete siblings. However, it does not explicitly name sibling tools like update_customer_geographic_access_scope or get_user_geographic_access_scope, so differentiation relies on wording rather than explicit contrast.
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 invocation context: the authenticated tenant must be the hierarchy root and the target must be the root or a child customer. It also names the required permission, UsersManager. It does not explicitly say when not to use it or point to alternative tools for viewing or deleting scope, but the preconditions and operation context are strong enough for an agent to understand when this tool applies.
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 readOnlyHint=true annotation, description discloses latency for complex questions and error handling behavior. Does not contradict annotations. Could add more about response structure but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a note, no wasted words. Front-loaded with purpose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the open-ended Q&A nature with no output schema, description covers usage scope, latency, and error recovery. Could mention follow-up capabilities but overall 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?
Schema coverage is 100% with clear descriptions for each parameter. Description does not add new parameter details beyond schema. Baseline score adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: asking DoiT AVA questions about cloud costs, infrastructure, etc. It specifies the verb 'ask', the resource 'AVA', and the domain, distinguishing it from general-purpose AI queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use only for DoiT or cloud-specific questions, not general AI. Mentions latency and error handling guidance. Lacks explicit sibling tool alternatives but provides clear context boundaries.
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?
Description mentions creation and confirmation step, but does not elaborate on destructive potential (destructiveHint=true). Annotations already indicate mutation and destructiveness; description adds minimal extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no 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?
No output schema exists; description does not mention return value (e.g., created folder ID). Otherwise adequate for a create tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all three parameters (name, description, parentFolderId) with descriptions. The tool description adds no additional meaning beyond the schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'create a new Cloud Analytics folder' with specific verb and resource. Distinguishes from siblings by explicitly naming create_report and create_label as different tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when...' and 'Do NOT use this for...' with specific alternatives. Also instructs to ask user for confirmation before execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that for customers comments are always public, and for employees the private flag controls internal notes. Adds context beyond annotations, which only indicate read/write and destructiveness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and then behavioral nuance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential behavioral differences and parameter roles. Lacks mention of return value or success indication, but given no output schema, this is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so description adds minimal extra value. The description reinforces the private flag behavior already in schema, but includes role-based context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'adds' and resource 'comment to existing support ticket'. It distinguishes from sibling tools like list_ticket_comments (lists) and create_ticket (creates ticket).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (to add comment) and includes context about public vs private for customers vs employees. Does not explicitly state when not to use or mention alternatives like list_ticket_comments.
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 safety profile is clear. The description adds that it returns matching diagram files but does not elaborate on behavior like pagination or sorting. Given annotations cover the main safety concerns, a score of 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 extremely concise: three sentences covering when to use, what it returns, and negative usage with alternatives. Every word is essential, and the structure 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 find tool with one parameter and no output schema, the description covers the essential: purpose, return type, and negative guidance. It could specify the return format more precisely (e.g., list of file paths), but it is mostly complete given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the 'resources' parameter (array of resource IDs). The description adds no additional meaning beyond the schema. With 100% schema coverage, baseline is 3, and the description does not enhance it further.
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 specifies the tool's purpose: finding architecture/cloud infrastructure diagrams. It uses a specific verb ('find') and resource ('cloud diagrams'), and distinguishes it from siblings by stating what it does not cover (cost analysis, incidents) with explicit tool names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: when to use (user wants diagrams), and when not to use (cost analysis -> run_query, incidents -> get_cloud_incidents). This directly helps an agent decide between sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds that the tool accepts partial name (case-insensitive). It could further clarify behavior on multiple matches or no match, but overall sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and usage boundaries. 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 tool with two parameters and no output schema, the description covers purpose, usage boundaries, and parameter behavior. It could mention response handling for multiple or missing matches, but overall fairly complete given 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?
Schema description coverage is 100%, so the baseline is 3. The description adds context that the name parameter is for when ID is unknown, but this is implicit from the parameter descriptions. No additional meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'view details of a specific cloud asset', clearly identifying the verb and resource. It distinguishes from siblings by warning against using for listing (list_assets) or cost analysis (run_query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use ('when the user wants to view details') and when-not-to-use ('Do NOT use for listing assets or cost analysis'), naming alternatives. However, it lacks guidance on handling partial name matches that return multiple assets.
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 and destructiveHint, so the description adds value by specifying the data returned (node change counts, diagram import/sync state) and the requirement for start/end dates. It does not contradict annotations and provides additional behavioral context beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with usage context and output description. Every sentence is informative and there is no redundancy. It efficiently communicates purpose, output, and requirements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two simple parameters, no output schema, and annotations covering safety, the description provides sufficient context: what stats are returned (node changes grouped by service, diagram states) and use cases (auditing, drift detection). It could mention limits like maximum time range, but overall it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (coverage 100%). The description emphasizes that both are required and in RFC3339 format, which reinforces the schema but doesn't add substantial new meaning. Baseline for high coverage is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool returns activity statistics for cloud infrastructure diagrams over a time period, including node change counts grouped by cloud service and diagram import/sync state. It distinguishes itself from sibling tools by focusing on aggregated stats over time, not individual diagram details.
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 starts with 'Use this when the user wants activity statistics...' providing explicit usage context. It does not list alternatives or exclusions, but the context is clear enough for an agent to decide when to use this tool vs. others like get_cloud_diagram_components or get_cloud_diagram_cost_snapshot.
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=true. Description adds that it returns a list and supports partial name filtering, but this is also present in the schema. No additional behavioral traits are disclosed beyond what annotations and schema already cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with usage context. Every sentence adds value without redundancy. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and annotations indicating safety, the description provides clear purpose, usage guidelines, and differentiation. It lacks details about the output format, but given no output schema, it is still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions partial name filtering, but this is already documented in the schema's description for the name parameter. No new meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns a list of cost allocation rules or configurations, uses a specific verb ('list'), and distinguishes from sibling tools like run_query and list_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly states when to use (user wants to see allocations) and explicitly says when not to use (cost queries or labels) with direct alternative tool names (run_query, list_labels).
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=true and destructiveHint=false, so the safety profile is clear. The description adds only that it returns a list of annotations, which is basic. No additional behavioral context like pagination behavior or rate limits is provided, but given annotation coverage, 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?
Two sentences, front-loaded with usage context, and zero wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with good annotations and full schema coverage, the description is mostly complete. It could explicitly state the return type (list of annotation objects) or mention that results are paginated (implied by parameters), but the description is adequate 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?
Schema description coverage is 100%, with each parameter already well-documented in the input schema. The description adds no extra meaning beyond the schema, so baseline 3 is correct.
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 is for listing calendar annotations or notes on cost data, with specific verb 'see... returns a list'. It distinguishes from sibling tools list_labels and list_alerts by explicitly naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the user wants to see calendar annotations or notes on cost data' and provides negative guidance with alternatives: 'Do NOT use this for labels (use list_labels) or alerts (use list_alerts)'.
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?
Annotations already declare this as read-only and non-destructive, and the description adds substantial behavioral detail beyond that: item contents, trailing 30-day aggregates, YTD/lifetime savings per Savings Plan type, monthlyPotentialSavings, sum-across-items guidance, and complete pagination semantics including when to stop. This goes well beyond what the structured annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The functional explanation is well structured and information-dense, but the opening sentence about evaluating commitments, planning purchases, and optimizing costs is a promotional preamble that does not help an agent select or invoke this specific endpoint. This unnecessary first sentence prevents a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly takes responsibility for explaining return-item fields, aggregation semantics, and pagination termination conditions, so an agent can both call and interpret the response. Minor gaps remain around maxResults behavior and the X-Tenant-Id parameter, but the essential invocation and response interpretation are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics for pageToken by explaining to pass the response's pageToken value and stop when no pageToken is present. However, with schema coverage at only 25%, it does not compensate much for maxResults and X-Tenant-Id, leaving those largely to inference from 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: 'Returns all AWS organizations (accounts) accessible to the authenticated tenant.' It also gives the tool a clear role as 'the entry point to discover AWS organization account IDs, and organization-level onboarding status,' which distinguishes it from sibling tools like list_aws_member_accounts and list_aws_organizations_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use as the entry point to discover AWS organization account IDs, and organization-level onboarding status.' This tells an agent when this is the right first call, but it does not explicitly name alternatives or provide when-not-to-use conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns a cursor-paginated list with metadata, status, and last execution info, which provides 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 description is two sentences: one stating the purpose and usage, one describing the return. It is concise and front-loaded with the most important 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?
Despite lacking output schema, the description mentions what is returned (metadata, status, last execution info). The tool is simple with no nested objects, and annotations cover safety. This is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters have descriptions. The description adds only minor context about cursor-pagination, which relates to pageToken, but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('see' i.e., list) and the resource ('CloudFlow automation flows'). It distinguishes from sibling list_cloudflow_connections and list_cloudflow_templates by specifying 'automation flows'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the user wants to see their CloudFlow automation flows,' providing clear context. It does not specify when not to use or alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context beyond the obvious 'returns a list.' It does not mention pagination behavior or any side effects, but given the annotations, the description is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—only two sentences—and front-loaded with the core purpose. Every sentence adds value: first tells what it does, second tells when not to use it and alternatives. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 params, no output schema, and good annotations, the description explains the purpose and usage clearly. It lacks detail on return format or pagination, but the schema covers parameters. Overall, it is sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning to the parameters (filter and pageToken) beyond what the schema already provides. No extra context or format details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Returns a list of dimension types and values that can be used with run_query,' using a specific verb ('list' implied) and resource ('dimensions'). It distinguishes from siblings by explicitly stating when not to use it and naming alternatives (run_query, list_allocations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the user wants to see available dimensions for cost analysis queries.' It also provides explicit exclusions: 'Do NOT use this for running cost queries directly (use run_query) or viewing allocations (use list_allocations).' This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, openWorldHint. Description adds that it returns list with amounts, dates, status but no further behavioral traits. Adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with use case, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, description covers return fields and usage guidance. Could mention pagination behavior more explicitly, but 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?
Schema coverage is 100% for the single parameter pageToken. Description does not add extra meaning beyond schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns invoices with amounts, dates, and status, and differentiates from siblings by explicitly excluding cost analysis and budget tracking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (view invoices, billing history, payment records) and when not to, naming alternative tools run_query and list_budgets.
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, destructiveHint=false, so safety is clear. Description adds that it returns a list and mentions filtering by platform, but no additional behavioral traits 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?
Two sentences, zero waste, front-loaded with primary purpose. Each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description provides purpose, usage, exclusions, and basic behavior. No missing critical info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the only parameter 'platform' with a description. The description does not add further semantics beyond 'Filter products by platform'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'products', and explicitly distinguishes from siblings by naming alternatives for cloud incidents and platforms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('user wants to see available DoiT products or services') and when-not-to-use with specific sibling tool names (get_cloud_incidents, list_platforms).
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 safety profile is clear. The description adds useful context about return fields and filtering but does not cover pagination behavior or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with purpose and usage, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no output schema), the description covers purpose, return fields, filtering, and exclusions. It is complete enough for effective use, though it could optionally mention default page size.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description mentions partial subject filtering, which reinforces the schema but does not add new semantic information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists support tickets with status, priority, and platform, and explicitly distinguishes it from sibling tools for cloud incidents and cost alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (view tickets, check status, review issues) and when-not-to-use scenarios, naming specific alternative tools (get_cloud_incidents, list_alerts).
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 description doesn't need to restate safety. The description adds that period1 includes the current month, which is useful behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 1 required, no output schema) and comprehensive annotations, the description is fully adequate. It explains the two-period concept, provides usage guidance, and doesn't miss critical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds context about rolling lookback vs explicit range, which is a nuance beyond the schema. But it doesn't significantly impact parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: compare spend between two time periods, with examples. It also distinguishes it from run_query for multi-period analysis, making the purpose 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (two-period comparison) and when not to (more than two periods, use run_query). Also explains the difference between period1 (rolling lookback) and period2 (explicit range), providing clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description reveals idempotency ('Repeating the request is idempotent'), the resulting unassigned state, and the permission requirement. No contradiction with annotations; the destructive hint aligns with the delete semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each carrying distinct information (action, result, preconditions, idempotency, permission). The opening 'Manage country-based access...' sentence is generic framing that adds little, but everything else earns its place and the core action is front-loaded in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, hierarchy-sensitive operation, the description covers semantics, resulting state, preconditions, idempotency, and authorization. The only real gap is error behavior when preconditions fail (e.g., a non-root caller), and with no output schema, the return value is unspecified.
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 only 33%: only customerContext is documented in the schema. The description indirectly constrains targetCustomerId by stating the target must be the root or a child customer, but it never names the parameters explicitly, and X-Tenant-Id receives no semantics beyond its self-explanatory name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Clears') with the resource ('the geographic scope') and the resulting state ('leaving it unassigned'), making the action unambiguous. It is naturally distinguished from siblings like update_customer_geographic_access_scope and get_customer_geographic_access_scope, and from delete_user_geographic_access_scope by resource type.
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 concrete preconditions: the authenticated tenant must be the hierarchy root, the target must be that root or a child customer, and the UsersManager permission is required. It stops short of a 5 because it never explicitly names alternatives for setting or reading the scope (e.g., update_customer_geographic_access_scope).
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?
Annotations establish that this is read-only and non-destructive, so the description's main burden is to explain the return shape. It does so in detail, documenting stats30d, monthlyStats, dailyCoverage, savingsTotals, and monthlyPotentialSavings, including caveats like lifetime being bounded by onboarding start. This is substantive value 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with useful field breakdowns, but it starts with a broad product pitch ('Evaluate current AWS commitments, plan and automate purchases...') that does not directly describe this specific tool. The key operational sentence is somewhat delayed, though the bulleted output documentation 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 read-only retrieval tool with no output schema, the description provides strong coverage of the return data and when to use the tool. The main gap is parameter semantics for managementAccountId and X-Tenant-Id, which are left mostly to the schema or inference, but overall the description is comprehensive enough to support correct 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?
Schema description coverage is only 33%, and the description does not explain the required managementAccountId parameter or the optional X-Tenant-Id parameter. It implies that a single organization is targeted, but it adds no concrete parameter-level guidance 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 that the tool returns a single AWS organization with Overview time-series fields, and distinguishes it from fetching every organization. It names the specific verb and resource ('Returns a single AWS organization') and even references the sibling List AWS Organizations to anchor the list-item fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this when you need a single organization's Console Overview in one call... without fetching every organization.' This provides clear selection criteria relative to the alternative list operation and makes the decision boundary easy for an agent to apply.
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 description adds context about what details are included (GCP/AWS config, collaborators, status) but does not describe additional behaviors like authentication or rate limits. The description aligns with 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?
Two sentences with no fluff. The first sentence defines purpose and included details; the second provides negative guidance. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description is complete. It explains what the tool returns (config, collaborators, status) and is clearly differentiated from 90+ sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter connectionId, with a description 'The ID of the CloudFlow connection to retrieve.' The tool description does not add extra meaning beyond stating it's an ID, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'view the details of a specific CloudFlow cloud provider connection by its ID, including its GCP/AWS configuration, collaborators, and status.' It uses a specific verb and resource, and distinguishes from siblings by explicitly stating what not to use it for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use (view specific connection), when not to use (do not list all or trigger), and names alternative tools: list_cloudflow_connections and trigger_cloud_flow.
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. Description adds meaningful context about ownership scope (tenant from bearer token), which clarifies the security boundary not visible in annotations. Doesn't mention output format or pagination, but with readOnlyHint the bar is lower; still adds 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?
Description is a single informative sentence with a follow-up on required access. It is front-loaded with purpose, then scope, then access requirements. Efficient use of words without redundancy, though could be slightly more structured but not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter retrieval tool with clear annotations and no output schema, the description covers purpose, scope, access conditions, and special-case usage (customerContext). It could mention what the template contains or return format, but given low complexity and good annotations, this is nearly complete. Missing explicit statement of what identity the template is returned for, but implied.
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 50% (only customerContext has a description, templateID has none). The description adds context for customerContext (required for DoiT employees, omit for direct customers) which is not in the schema. templateID remains undocumented, but description's context about owner and scope helps infer its meaning. Compensates well for the 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?
Description states it manages contract templates for PartnerOps resellers, returns a single template owned by the authenticated tenant, and clearly distinguishes from sibling 'list_contract_templates' which presumably lists multiple templates. The verb 'get' and resource are explicit.
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 context (PartnerOps resellers, T1/T2) and notes when customerContext is required (for DoiT employees) vs omitted for direct customers. Doesn't explicitly say when not to use it, but clear context implies standard retrieval. Lacks exclusion of alternatives beyond the sibling list tool, but sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's mention of 'returns a list' is consistent but adds limited new 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?
Two concise sentences front-load the purpose and usage guidelines with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter read tool with clear siblings, the description is complete and sufficient for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description; the description does not add further 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 the tool retrieves assigned resources for a specific label, and distinguishes from sibling tools like get_label and list_allocations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('when the user wants to see which resources are assigned') and when not to use (for label details or allocations), with alternative tool names provided.
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 mark the call as read-only and non-destructive, and the description enriches this by detailing pagination behavior ('call again passing the response's pageToken ... Stop once the response has no pageToken') and the returned information (30-day statistics, monthlyPotentialSavings per SP type). 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 main functional content is compact and the pagination advice is practical. The first sentence is promotional and not strictly necessary, but it does provide usage context, so the overall length is reasonable.
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?
Without an output schema, the description covers the core return values and the pagination protocol, and the schema covers parameter constraints. It omits some detail about X-Tenant-Id and response shape, but an agent has enough to call and consume the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, so the description needed to compensate. It explains pageToken semantics and links managementAccountId to the 'specified AWS organization', but it leaves maxResults and X-Tenant-Id unexplained in either the schema or 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 states 'Returns all member AWS accounts under the specified AWS organization that have active or historical commitment coverage', providing a specific verb, resource, and scope. This clearly differentiates it from sibling tools like list_aws_savings_plans or get_aws_member_account.
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 opens with a clear use-context: 'Evaluate current AWS commitments, plan and automate purchases, and optimize cloud costs with PerfectScale for Commitments'. It does not explicitly name alternatives or exclusion conditions, but it gives enough context for an agent to select this list tool over the many commitment/planning siblings.
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?
Annotations already mark the tool read-only and non-destructive, and the description adds substantial behavior: stable ordering, empty items vs 404, partial-field responses, and exact pagination error codes. This goes well beyond the structured annotations without contradicting them.
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 content is dense and front-loaded, with useful operational details. However, the stable commitment-type order is stated twice, the pagination paragraph redundantly repeats the call-again instruction, and the opening sentence is more promotional than necessary.
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 paginated list with no output schema, it covers ordering, empty responses, 404/onboarding cases, pagination tokens, and rowCount semantics. It stops short of describing planned-purchase item fields or the required managementAccountId parameter semantics, but the invocation-relevant behavior is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description must compensate. It does explain service as a filter, maxResults limits (default 50, max 500), and pageToken handling, but it never explains the required managementAccountId or X-Tenant-Id semantics, leaving important parameters 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 clearly states the resource (planned purchases / laddering projections for the AWS organization) and the verb (Returns). It also clarifies scope — one item per commitment type — which differentiates it from tools that list existing commitments like list_aws_savings_plans or list_aws_reserved_instances.
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 explains behavior with no filters, with a filtered commitment type, and for non-onboarded organizations, and explicitly routes 404 cases to GET /ps4commitments/v1/aws/organizations for onboardingStatus. It does not name sibling tools as alternatives for existing commitments, so some when-not-to-use guidance remains 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, and the description adds useful behavioral details: the set is small and returned in full, and each suggestion can be accepted or dismissed. It also explains the workflow (create budget via POST before accepting), which goes beyond annotations. 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 concise, two sentences, and front-loaded with the core purpose. The first sentence explains the tool's function and follow-up actions, while the second provides scale and return behavior. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description covers the essential context: what it returns, the size of the result set, and the follow-up actions (accept/dismiss). It also links to the budget creation endpoint, enhancing completeness for a list tool in a workflow.
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 sole parameter customerContext has a complete description in the schema (100% coverage), explaining when it is required and for whom. The tool description adds no additional parameter info, but since the schema covers it fully, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists AI-generated budget suggestions, uses the specific verb 'list' and resource 'budget suggestions', and distinguishes from siblings like accept_budget_suggestion and dismiss_budget_suggestion by focusing on the listing aspect. It also specifies 'pending' suggestions, narrowing the scope.
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 context: it returns suggestions that can be accepted or dismissed, and mentions the need to create a matching budget before accepting. This gives clear context but does not explicitly state when to use this tool versus alternatives like list_budgets or accept_budget_suggestion. The related siblings are evident, so guidance is adequate though not exhaustive.
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 goes beyond the annotations by disclosing that results are limited to quotas retained by DoiT's collectors, are sorted by utilization percentage, and require pagination via pageToken. These are important behavioral traits not captured in 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 appropriately structured, starting with the purpose, then limitations, sorting, and pagination. It is slightly verbose but each sentence adds necessary context. It is not overly long or redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality, limitations, sorting, and pagination. It does not mention potential errors or authentication requirements beyond 'for the authenticated customer,' but given the read-only nature and existing annotations, it is sufficiently complete for a user to understand when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only includes a description for customerContext. The tool description explains pagination (pageToken) and sorting (utilization), but does not elaborate on cloudProvider or minUtilizationPercent. These parameters are relatively self-explanatory from their names and enum/min-max constraints, so the description adds limited extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: monitoring and returning service quota usage snapshots. It distinguishes this from other tools by explicitly mentioning the resource type (service quotas) and the data source (DoiT's monitoring collectors).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's purpose and limitations, including that results are not a complete or live inventory. It also provides pagination instructions, which are practical usage guidelines. It does not explicitly mention alternatives, but given the specific resource type, it is clear when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only (readOnlyHint=true) and non-destructive (destructiveHint=false). The description adds context: internal tool, AND-combined conditions, any-of within lists, pagination via nextPageToken, and authorization requirement. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but well-structured, starting with purpose, then listing fields, then explaining logic, pagination, auth, and usage guidance. It is comprehensive without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (17 optional params, no output schema), the description covers purpose, behavior, pagination, auth, and comparison to siblings. It mentions return value (summary + nextPageToken) but lacks details on error handling or rate limits, which are acceptable given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description does not add significant meaning beyond the detailed schema descriptions for each parameter; it restates categories but not extra semantics. The logic of AND-combination and any-of is behavioral, not parameter-specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches across ALL DoiT customers by specified attributes, with a specific verb ('search') and resource ('customers'). It distinguishes from siblings by advising to use other tools for drilling into a specific customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('FIND customers across the base') and when not (non-doers get auth error), and suggests alternatives: 'use other tools to drill into a specific customer'.
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 destructiveHint=true; description adds that this modifies an allocation and instructs to ask user confirmation. However, it does not disclose side effects, permissions required, or irreversibility, which would enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, avoids redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, nested objects), the description is brief. It covers purpose and usage boundaries but does not explain the parametrical structure, return value, or effects of different parameter combinations. The detailed schema compensates partially, but missing output schema and minimal context leave gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all six parameters with descriptions (100% coverage), so baseline is 3. The description adds no additional parameter meaning beyond what the schema provides, such as how to structure rules or the difference between 'rule' and 'rules'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it modifies an existing cost allocation, using specific verb 'modify'. It distinguishes from creating (create_allocation) and viewing (list_allocations), 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (modify existing allocation) and when not to (creating or viewing), naming alternative tools. Also instructs to ask user for confirmation, providing clear usage boundaries.
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 indicate this is a non-read-only, non-destructive operation, but the description adds valuable behavior: it streams real-time progress, returns the created flow's ID, the builder's answer, and the build steps that ran. This goes beyond the annotation flags and helps the agent set expectations about the tool's side effects and result format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loads the trigger condition, and includes the key usage distinction and output summary. Every sentence earns its place without redundancy or unnecessary detail.
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 lack of an output schema, the description adequately covers return values and the streaming behavior. It omits only minor details such as the exact meaning of 'builder's answer' and how streaming is delivered, but the core information an agent needs to call this tool correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents both `question` and `conversationId` clearly. The description adds general context about the natural-language build process and return values but does not materially deepen parameter-level understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('build a brand-new CloudFlow automation from scratch') and specifies the output: the new flow's ID, the builder's answer, and the build steps. It also differentiates itself from the sibling tool refine_cloudflow, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use the tool ('when the user wants to build a brand-new CloudFlow automation from scratch using natural language') and when not to, naming the alternative: 'Use refine_cloudflow to change an existing flow; use this only to create a new one.' This gives clear selection guidance.
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?
Annotations already indicate destructive and non-read-only, but the description adds significant context: soft cancel behavior, retention of invite document, visible cancelled status, token invalidation, and error cases. 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 6 sentences covering purpose, behavior, errors, and permissions. It is well-structured and front-loaded with key info, though the first sentence is somewhat generic ('Manage users...') and 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?
No output schema exists, but the description explains the effect (soft cancel, token invalidation, status) and error codes. It mentions required permission. Lacks detail on dryRun and Idempotency-Key, but overall sufficient for a cancel 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?
Schema coverage is only 25% (one parameter has description), and the tool description does not explain dryRun, Idempotency-Key, or the id format. The description only implies id is the invite ID. Given low schema coverage, 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 marks an invite as Cancelled and invalidates the token, distinguishing it from full deletion via DELETE. It specifies the verb and resource, and differentiates from sibling tools like delete_user and invite_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (soft cancel) versus DELETE for full removal. Also mentions error conditions (404, 409) and required permission (usersManager), providing clear context for when to invoke.
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. Description adds behavioral details: returns top-N items ranked by cost descending, default months=1 includes current month. This goes beyond annotations with specific operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, minimal and efficient. First sentence states purpose with examples, second provides alternative. No 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?
No output schema, but description notes returns top-N ranked list. Lacks details on cost format (e.g., currency), but sufficient for typical use. Annotations and schema fill gaps well, making it nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. Description does not add significant new meaning; it restates the grouping dimension and cloud alias, which are already in schema. Baseline 3 is appropriate as schema fully documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'simple cost breakdown by service, project, or cloud provider' with examples, clearly indicating the tool's function and output (top-N ranked by cost descending). This distinguishes it from siblings like run_query for complex queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when the user wants a simple cost breakdown' and provides an exclusion: 'For complex multi-filter or multi-metric queries, use run_query instead.' This gives clear when-to-use and when-not-to-use with an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint: true and destructiveHint: false, so the description carries less burden. It adds value by stating returns 'monthly cost data points' and the optional breakdown. No contradictions. The description could mention auth or rate limits, but annotations cover safety, so a small deduction 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 two sentences, front-loaded with purpose and examples. Every sentence is valuable and non-redundant. It achieves high information density without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 optional parameters and no output schema, the description adequately explains the output ('monthly cost data points, optionally broken down'). It covers the main use case and distinguishes from siblings. Minor gap: could mention the default months=6 explicitly, but the schema already has a default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds minimal extra meaning: it mentions 'optionally broken down by service/project/cloud' which maps to groupBy, but the schema already describes it. The usage context is slightly enriched but not enough to raise the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to show monthly spend over time. It uses specific verbs ('see', 'returns') and identifies the resource ('monthly cost data points'). The examples ('Show me my cost trend') make it concrete. It also distinguishes from sibling tools by noting the alternative for daily/custom intervals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use guidance with examples ('when the user wants to see monthly spend over time'). Explicit when-not-to-use: 'For daily granularity or custom time intervals, use run_query instead.' This is a clear alternative, satisfying the highest level of this dimension.
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?
Description adds behavioral context beyond annotations by instructing the agent to confirm with the user before executing. Annotations already indicate destructive nature, but confirmation step is a valuable addition.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and usage guidelines. Every part earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested config object and no output schema, the description provides adequate context. It could mention return values or idempotency but adds enough for a confident agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains parameters thoroughly. The description adds minimal extra semantics (e.g., 'thresholds' maps to config.value). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: setting up a new cost alert with thresholds and notification settings. It also distinguishes it from sibling tools like create_budget and list_alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use (setting up a new cost alert) and when-not-to-use (not for budgets or viewing alerts), with specific sibling tool names as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint false and destructiveHint true, but the description adds the valuable context to ask user for confirmation, mitigating the potential destructive nature. 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?
Two sentences convey purpose, usage boundaries, and a confirmation step with no extraneous information. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters and no output schema, the description covers the core purpose and usage context. It lacks details on return behavior but is sufficient for an informed agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description does not add additional parameter semantics beyond what the schema provides, meeting the baseline expectation.
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 adds a new annotation to mark a specific date or event in cost data. It explicitly distinguishes from sibling tools create_label and create_alert, eliminating ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (user wants to mark a date/event) and when-not-to-use (for labels or alerts), and instructs to ask user for confirmation, offering clear 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 indicate destructiveHint=true and openWorldHint=true. The description adds the instruction to confirm with the user before executing, which reinforces cautious behavior. While it doesn't detail further side effects, it aligns with annotations and adds practical guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Essential information is presented efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required params, no output schema), the description covers purpose, usage boundaries, and a safety step. It is complete enough for effective agent use, though could mention the scope (e.g., workspace).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so schema alone is sufficient. The description does not add extra semantic detail beyond what the schema provides, maintaining baseline adequacy.
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: 'create a new resource label'. It distinguishes from sibling tools like list_labels and create_annotation, ensuring the agent can select the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (user wants to create a label) and when not to use (viewing labels or annotations), with alternatives. Also instructs to ask user for confirmation, providing clear action boundaries.
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 provide readOnlyHint=true. The description adds that it accepts ID or partial content match (case-insensitive), but does not discuss error handling or return format; still adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main purpose and include quick exclusions. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage boundaries, and parameter behavior. Does not specify return format or error scenarios, but sufficient for the tool's simplicity given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema descriptions are clear. The description adds context about using one parameter over the other, but this is marginal beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'view details' and resource 'specific annotation', distinguishing it from sibling tools like list_annotations and list_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (user wants to view details of a specific annotation) and when not to use (listing all annotations or labels), with named alternatives (list_annotations, list_labels).
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 goes far beyond the readOnlyHint/destructiveHint annotations by disclosing three distinct error semantics (404 for missing/expired/wrong-tenant operationId, 425 for non-terminal state, 422 for failed/canceled operations), the response shape equivalence to GetReportResponse, and the fact that the status endpoint does not inline result data. This level of behavioral detail — especially the tenant-scoping and terminal-state nuance — is exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense with high-value information (error codes, retry guidance, response shape, exclusivity claim), but it runs about 150 words and opens with a boilerplate sentence that doesn't uniquely describe this tool. The error-code enumeration is thorough but could be tightened into a more scannable form. Adequate structure but not clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 parameters, no output schema, and no enums, this description over-delivers: it covers success shape, all three failure modes, the operational pattern (poll until terminal, then fetch results), and the relationship to the sync endpoint and the polling endpoint. The only missing piece is an explicit pointer to where operationId originates, which is reasonably inferred from 'async report operation' and the sibling async_run tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is exactly 50%: customerContext has a full schema description, while operationId has none. The tool description compensates by giving operationId lifecycle meaning (must reference a succeeded async report operation; invalid/expired operations yield 404 and non-terminal ones yield 425), which helps an agent understand what value to pass. Small gap: it never explicitly says operationId comes from a prior async run call (e.g., async_run_report_by_id or async_run_inline), though this is strongly implied.
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 specific behavior: returns the result of a succeeded async report operation, with concrete metadata fields (id, reportName, owner, type, createTime, updateTime, urlUI) and the explicit distinction from the sync GetReportResponse. However, the opening sentence "Manage Cloud Analytics reports and get reports data in JSON format" is generic boilerplate that would apply to most sibling report tools, which slightly muddies the focus before the specific behavior is stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit routing guidance: when the operation has not reached a terminal state (425), the agent is told to poll the operation status endpoint instead and to honor its Retry-After guidance. The closing sentence — "this is the only endpoint that returns it" — tells the agent why this tool must be chosen over the polling endpoint for result data. This is model guidance for when-to-use vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description's behavioral disclosure is minimal beyond restating the query intent. It does not add details like error handling, rate limits, or side effects, but the safety profile is already clear from 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 three sentences long, front-loaded with the primary use case. Every sentence adds value—purpose, input format, output summary—without redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a single parameter and no output schema, the description fully covers the required information: what it does, what input to provide, and what the response contains. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes accountID with type string and a basic description, but the tool description adds crucial semantic detail: it accepts both AWS account IDs and Azure tenant IDs. This clarification goes beyond the schema and helps the agent correctly populate the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to check supported DoiT CloudConnect features and permission status for a given cloud account. It specifies the input (AWS account ID or Azure tenant ID) and output (list with permission status). This is a specific verb-resource combination that distinguishes it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description begins with 'Use this when the user wants to know...', providing clear context for when to invoke the tool. It does not explicitly mention when not to use it or alternatives, but the use case is well-defined and no sibling tool covers the same functionality, making the guideline sufficient.
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=true and destructiveHint=false, so the description's added value is in describing the outputs (total spend, trend, top resources, cost trend). It does not contradict annotations. It could mention the default interval behavior, but overall it adds useful 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 two sentences, front-loading the purpose and outputs, then giving requirements and exclusions. Every sentence is essential, no waste. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately describes the return contents (total spend, trend, top resources). It covers purpose, usage, and exclusions. Minor missing details like interval default do not significantly hinder invocation. Overall 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already documented. The description reinforces the required parameters and date format but adds no new meaning beyond the schema. The interval parameter's default is not mentioned, but the schema covers its enum values. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides a cost snapshot for a specific diagram layer over a time period, listing outputs like total spend, trend percentage, top resources/services, and cost trend. It distinguishes from siblings by specifying the scope (layer-specific) and explicitly excluding account-wide or budget analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (for a specific layer cost snapshot) and when not to use (for account-wide cost analysis or budgets), providing alternative tools run_query and list_budgets. This gives clear guidance for selection.
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 richly discloses behaviors beyond the readOnly/openWorld/destructive annotations: null input semantics for non-action nodes, payload visibility timing during polling, sensitive-value redaction, 64KB truncation behavior with `truncated`/`totalBytes`, 404 semantics for cross-tenant/cross-flow access, and the fan-out limitation. This is exemplary behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, every paragraph earns its place by covering a distinct behavioral concern: purpose, input/output semantics, timing, redaction, truncation, and error behavior. The description is front-loaded with the main purpose and uses bold formatting to highlight a critical non-error condition.
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 there is no output schema, the description thoroughly covers what the tool returns, how to interpret node input/output, pagination-like truncation behavior, redaction, and failure/error cases. It is sufficiently complete for an agent to invoke the tool and interpret its response 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?
The schema only documents `customerContext`, leaving `runId` and `flowId` with no description and 33% schema coverage. The description does not compensate by explaining where these IDs come from, how they should be formatted, or how they relate to list_cloudflow_flow_runs. The parameter names are self-evident, but the description adds no parameter-level 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 quickly moves past the generic opener 'Manage CloudFlow' to a precise statement: it 'returns a run's status and, for each node, the JSON it consumed and produced.' It also establishes the tool's diagnostic role ('why a run failed'), which clearly distinguishes it from sibling list/detail tools like list_cloudflow_flow_runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'This is how you find out *why* a run failed, or that it succeeded while producing the wrong data' gives a clear, strong usage signal. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for selection.
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 provide readOnlyHint=true and destructiveHint=false, so the description carries a lighter burden. It adds value by specifying that only 'active' incidents are checked and mentions target platforms (AWS, Google Cloud, Azure), which aligns with the schema's enum and adds 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 just two sentences. The first sentence establishes the core purpose and scope, and the second provides exclusions. Every word is essential, and the structure front-loads the primary function, making it efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no output schema, the description covers purpose, usage context, and alternatives. It mentions the three main cloud platforms. However, it does not hint at the pagination parameter (pageToken) or filter format, though those are well-documented in the schema. Given the overall complexity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters; it only mentions platforms broadly, but the schema already provides detailed enum values and filter examples. No parameter-specific elaboration is given, so the score remains at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Use this when the user wants to check for active cloud platform outages...' which clearly states the verb 'check' and the resource 'incidents'. It also distinguishes from sibling tools by explicitly telling what NOT to use it for (cost anomalies or support tickets), leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance ('check for active outages') and when-not-to-guidance with named alternative tools ('use get_anomalies or list_tickets'). This makes it easy for an AI to decide between this and closely related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and destructiveHint, so safety profile is clear. Description adds that it returns 'full dataset metadata and schema', providing 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?
Two concise sentences, front-loaded with usage context, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a read-only retrieval tool: explains purpose, return content, and exclusions. No output schema, but description mentions return details.
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 describes parameter 'name' with description, achieving 100% coverage. However, description says 'by its ID' while parameter is 'name', creating a slight mismatch that could confuse agents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves details of a specific DataHub dataset. Uses specific verb 'view details' and identifies resource. Distinguishes from siblings by naming alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (view specific dataset) and when not to use (listing all datasets, cost queries), directly naming alternatives list_datahub_datasets and run_query.
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 and destructiveHint, so the behavior is partially transparent. The description adds context: accepts ID or partial name (case-insensitive), which is behavioral info not in annotations. 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 concise with three front-loaded sentences. Each sentence serves a purpose: purpose, input, exclusions. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with good annotations and full schema coverage, the description is complete. It explains when to use, input options, and exclusions. Could marginally benefit from describing the return value, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description mentions the two params and their alternatives, but does not add significant meaning beyond schema descriptions. The emphasis on 'either ID or partial name' is useful but not a major semantic addition.
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: viewing details of a specific Cloud Analytics folder. It specifies input options (ID or partial name) and explicitly distinguishes from sibling tools like list_folders and get_report_config, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: use when viewing a specific folder, avoid for listing all folders or viewing reports. Alternatives are named (list_folders, get_report_config), making the decision process 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 and destructiveHint. Description adds value by explaining the partial name matching (case-insensitive) and reinforcing the read-only nature. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose and clear usage guardrails. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only operation and lack of output schema, the description covers essential usage. It could mention behavior on no match, but the open world hint mitigates this. Complete enough for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for each parameter. The description restates that name is a partial match but does not add new semantic value beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: view details of a specific label. It differentiates from siblings by explicitly excluding listing all labels (list_labels) and annotations (list_annotations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('user wants to view details of a specific label') and when-not-to-use (listing labels or annotations) with alternative tool names. Covers both positive and negative usage contexts.
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 description adds context about the return value (per-user roles and public visibility) and the required parameters, but does not cover error cases or additional behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a distinct role: use case, return value, and prerequisite/guidance. Front-loaded with primary purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two parameters and no output schema, the description is mostly complete: it explains the return value at a high level (per-user roles and public visibility) and the parameter scope. Could be slightly more specific about the structure of the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions; the description restates the enum values and links resourceType to the resource ID, adding minimal extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (see who a resource is shared with), the resource (sharing settings for alerts, budgets, reports, allocations), and differentiates from listing tools via explicit 'Do NOT' statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (user wants to see sharing) and when not (listing resources), providing specific alternative tools (list_alerts, etc.).
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 destructiveHint=true. The description adds context about requiring user confirmation before execution. Could be improved by mentioning that inviting may trigger an email or require permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy. Purpose is stated first, followed by usage guidance and exclusions. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage context and parameter confirmation. Missing details on return value, but without output schema, it is acceptable. Could mention any side effects like triggering an invitation email.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add substantial meaning beyond schema, but it reiterates the need to confirm the listed parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: inviting a new person to the organization. It distinguishes from sibling tools 'update_user' and 'list_users'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly indicates when to use (inviting new person) and when not to use (updating or listing users). Also advises to confirm email, role, and organization before executing, guiding the agent's interaction with the user.
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?
Description confirms read-only behavior (consistent with annotations readOnlyHint=true) and adds that the result is paginated, which is beyond annotations. No behavioral traits are hidden. Annotations already cover safety, so description adds useful pagination context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states primary purpose, second states exclusions. No redundant phrases, all content 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?
Tool has 5 optional params, no output schema. Description covers usage context, pagination, and exclusions. It could mention the return format (alert objects) but not essential given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description does not add extra semantic information about parameters beyond what the schema provides, meeting the baseline expectation.
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 'Use this when the user wants to see their cost alerts or check alert configurations', specifying the verb 'see/check' and resource 'cost alerts/configurations'. It distinguishes from sibling tools get_anomalies and list_budgets by explicitly excluding them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use (view alerts/configurations) and when-not-to-use (anomaly detection and budget tracking) with alternative tool names (get_anomalies, list_budgets). This leaves no ambiguity.
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 description does not need to restate safety. It adds value by disclosing pagination and partial name filtering behavior. No contradictions. Could mention return format but not required.
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 clear sentences, front-loaded with purpose, no unnecessary words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description covers purpose, exclusions, and pagination. It is sufficiently complete given the schema and annotations. Slight gap on return structure, but overall solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions partial name filtering, which adds context to the 'name' parameter, but otherwise does not elaborate on other parameters. Adequate but not exceptional.
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 to use this tool for browsing cloud assets, subscriptions, or resources. It specifies the verb 'browse' and the resource 'assets'. It also distinguishes from siblings by explicitly listing what not to use (cost analysis, invoices).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use (browsing assets) and when-not-to-use (cost analysis -> run_query, invoices -> list_invoices). This gives clear context and alternatives, satisfying the dimension fully.
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, destructiveHint=false, and openWorldHint=true. The description adds no contradictory or additional behavioral information beyond 'Returns a list of labels with their metadata.' Since annotations cover the safety profile well, a score of 4 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 only two sentences, front-loaded with purpose and usage guidance. 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?
Despite no output schema, the description covers purpose and guidelines well. Annotations provide safety context. Lacking an explicit note on pagination (given pageToken/maxResults) is minor, but overall the description is sufficiently complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for all 5 parameters. The description does not add any extra meaning beyond the schema. Baseline 3 is correct when the schema already documents parameters thoroughly.
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: 'see their resource labels or label configurations' and 'Returns a list of labels with their metadata.' It also explicitly distinguishes itself from siblings list_annotations and get_label_assignments, making it easy to select the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use ('when the user wants to see their resource labels or label configurations') and when-not-to-use ('Do NOT use this for annotations... or label assignments') with direct alternatives, offering clear 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 that the tool returns a prioritized list with estimated daily savings, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but efficiently conveys purpose, usage, and alternatives. It is concise and front-loaded with the core use case.
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 no output schema, the description adequately explains the return value (prioritized list with savings). It also covers all necessary context for correct invocation, including when to use and exclude.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description does not add extra semantics beyond listing categories, but baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists optimization recommendations/insights. It provides specific verb 'list' and resource 'optimization recommendations', and distinguishes from siblings by explicitly excluding cost anomalies and budget tracking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance (user asks about optimization, insights, etc.) and when-not-to-use (cost anomalies vs. get_anomalies, budget vs. list_budgets). This is exceptionally helpful for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true. Description adds only 'Returns a list of organizations', which is consistent but does not provide additional behavioral context (e.g., pagination, authentication 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?
Two concise sentences with front-loaded purpose and immediate exclusion guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with no output schema, the description adequately states what it returns. However, it doesn't detail the structure of the organization list, which may be inferred but not explicit. Still, completeness is high given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist. Schema coverage is 100% (empty schema). Baseline of 4 is appropriate; description confirms no inputs needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'use' and resource 'organizations' with scope 'in their DoiT account'. It explicitly distinguishes from siblings 'list_users' and 'list_platforms', eliminating ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'when to use' and 'when not to use' with named alternatives (list_users, list_platforms). Provides complete guidance for tool selection.
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 read-only and non-destructive behavior. The description adds value by mentioning pagination and the return content (IDs and metadata). No contradictions. Could mention rate limits or default page size but still strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, no fluff, front-loaded with the main purpose. Every sentence is necessary and contributes to clarity.
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 what the tool does, its paginated nature, and what it returns. Without an output schema, it provides sufficient context for a simple list tool. Could mention metadata scope but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for the two parameters (filter and pageToken). No elaboration on parameter usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and resource 'reports', and distinguishes from siblings like run_query and get_report_results by specifying it's for browsing saved reports. This meets the highest standard of purpose clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (user wants to see saved reports) and when not to (for queries or results), and names alternative tools. This provides excellent guidance on tool selection.
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 destructiveHint=true and readOnlyHint=false. The description adds valuable context: data becomes available in ~15 minutes and asks for confirmation before execution. 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?
Five well-organized sentences that front-load the purpose, then cover constraints, required fields, user confirmation, latency, and exclusions. No unnecessary words; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex ingestion tool with a rich schema and no output schema, the description covers purpose, usage guidelines, constraints, latency, and alternatives. It does not describe the return value or error handling, but these are partially covered by the annotations and schema. Very high completeness overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters thoroughly. The description restates that provider and timestamp are required and dimensions/metrics optional, but adds no new semantic meaning beyond what's in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool sends DataHub events for ingestion with a count range of 1–50,000 per call. It distinguishes itself from siblings by explicitly saying not to use for creating or viewing datasets, naming the correct alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when to use ('when the user wants to send DataHub events'), advises to confirm event count and provider details before executing, and provides counterexamples ('Do NOT use for creating datasets...'). This leaves no ambiguity about appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a destructive operation (destructiveHint=true). The description adds that it supports partial updates and advises to ask for user confirmation before executing. These are helpful behavioral details 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?
Three concise sentences with no superfluous content. The instructions are front-loaded and each sentence adds value: what it does, how it works (partial updates), and what to avoid.
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 mutation tool with clear annotations and full schema coverage, the description provides adequate context on usage and behavior. It does not describe return values, but no output schema exists, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. The description mentions 'partial updates' but does not elaborate on which fields can be omitted or how they interact with the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it modifies an existing cost alert, using the verb 'update' and specifying the resource. It distinguishes itself from sibling tools 'create_alert' and 'create_budget', 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (modify existing alert) and when not to (for creating new alerts or budgets), with direct references to alternative tools. This provides clear guidance for tool selection.
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 provide readOnlyHint=false and destructiveHint=true. The description adds value by stating 'Supports partial updates' and requiring user confirmation, which is additional behavioral context. No contradiction, but could elaborate on side effects given openWorldHint=true.
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 consists of three front-loaded sentences with no fluff. Each sentence serves a distinct purpose: stating the action, indicating partial updates, and providing usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (20 parameters, 3 annotations, no output schema), the description adequately covers the tool's purpose and usage but does not mention the return value (e.g., updated budget object) or address side effects hinted by openWorldHint. It is mostly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 20 parameters, so the baseline is 3. The description does not add additional parameter details, but the schema already provides comprehensive 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 'modify an existing budget' and 'Supports partial updates,' providing a specific verb and resource. It distinguishes itself from sibling tools by explicitly mentioning not to use for viewing (list_budgets) or creating (create_budget).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use the tool (modify existing budget) and when not to (view or create). It also advises to ask the user to confirm changes before executing, providing clear usage guidance.
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, the description discloses that the operation atomically replaces the existing scope, is idempotent for identical requests, and carries specific auth/permission requirements. This adds meaningful behavioral detail about mutation, replacement, and safety that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences with no filler. The main action and scope are front-loaded, followed by constraints, idempotency, and permission requirements. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key behavioral aspects: atomic replacement, hierarchy constraints, idempotency, and permissions. With no output schema, return behavior is not addressed, and parameter-level detail for X-Tenant-Id is thin, so it is not fully complete but is strong for a destructive update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description partially compensates by explaining that the targetCustomerId must be the root or a child customer and that the authenticated tenant must be the hierarchy root. However, it does not explicitly explain X-Tenant-Id or customerContext semantics, leaving some parameter meaning 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 a specific verb and resource: 'Atomically replaces the geographic scope for a target customer' within a customer hierarchy. It is clearly distinct from sibling tools like update_user_geographic_access_scope and update_geographic_access_custom_region, which target different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear eligibility context: the authenticated tenant must be the hierarchy root, the target must be the root or a child customer, and the UsersManager permission is required. It does not explicitly name alternatives or say when not to use this tool, but the context is strong 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 indicate destructiveHint=true; description adds auto-rename behavior when sibling has same name and asks for user confirmation. 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?
Four sentences, front-loaded with purpose, then usage guidelines and behavioral note. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With destructiveHint annotations and full schema coverage, description adequately covers use cases, exclusions, and auto-rename behavior. Lacks mention of id being required, but schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 parameters with descriptions. Description maps actions to parameters (rename->name, re-describe->description, move->parentFolderId) but adds minimal new info beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for renaming, re-describing, or moving an existing Cloud Analytics folder. It distinguishes from create_folder and update_report siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (rename, re-describe, move), asks to confirm changes before executing, and provides alternatives for creating folders and updating reports.
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 adds the important behavioral note to ask for user confirmation before executing, which is beyond the annotations that already indicate destructiveness. However, it does not detail potential side effects beyond modification.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four concise sentences, front-loaded with purpose and usage guidelines. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameter count and no output schema, the description sufficiently covers the tool's purpose, usage, and behavioral requirements. It could optionally mention return values, but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already provides full parameter descriptions. The description mentions partial updates but does not add significant new meaning beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies an existing label and supports partial updates. It explicitly distinguishes from create_label and update_annotation, making it easy for an AI agent to select the correct tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use when modifying an existing label, do not use for creating labels or annotations, and ask user for confirmation before executing. This covers both when-to-use and when-not-to-use with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and destructiveness (destructiveHint=true). The description adds the behavioral guideline to ask for confirmation. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and scope, second gives behavioral guidance and exclusions. Very concise and front-loaded 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?
Covers usage and main fields. No output schema, but description doesn't need to explain return values. Lacks mention of side effects like immediate application or cascading changes, but overall sufficient given annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already describes each parameter. The description only broadly mentions fields and does not add additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'user's information', listing example fields like name, job function, phone, language, or role. It also explicitly distinguishes from sibling tools invite_user and list_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Guidelines are explicit: use when the user wants to update user info, and do not use for inviting or listing. It also instructs to confirm changes before executing.
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?
Description adds the behavioral trait of requiring user confirmation before execution, which is not captured by annotations. Annotations indicate destructiveHint=true, which aligns. 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?
Three sentences that are front-loaded with purpose, followed by usage guidance and exclusions. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description fully covers purpose, usage conditions, and exclusions. An agent can correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters adequately. Description does not add additional semantic detail beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Use this when the user wants to create a new DataHub dataset' and distinguishes from sibling tools for viewing and sending events, providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly tells when to use (create) and when not to use with explicit alternatives (list_datahub_datasets, send_datahub_events), and advises to ask for user confirmation before executing.
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 provide readOnlyHint and destructiveHint. The description adds context that results are 'recent' and include 'severity and impact', which is useful 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?
Two sentences with no wasted words. The first sentence starts with 'Use this when' for immediate clarity, followed by a concise list of exclusions.
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 no output schema, the description mentions return fields (severity and impact). The tool has a single optional parameter, and the description covers purpose, usage, and output context. Complete for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% as the only parameter (pageToken) has a description. The tool description does not add extra semantics for this parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('check', 'returns') and clearly identifies the resource ('anomalies'). It also distinguishes from siblings by naming alternative tools for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (checking for cost spikes) and when not to use, with three specific alternative tools (list_optimization_recommendations, run_query, list_alerts). This is exemplary 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 that it returns full anomaly data including affected resources and cost impact, providing useful behavioral context 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?
Two sentences, front-loaded with purpose and usage guidelines, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter, no output schema, and clear annotations. The description covers purpose, usage, return content, and exclusion, making it fully informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the 'id' parameter. The description does not add additional meaning beyond restating the parameter purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies viewing details of a specific cost anomaly by ID and distinguishes from sibling get_anomalies which lists all anomalies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (view specific anomaly) and when not to use (listing all anomalies, recommending get_anomalies).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and destructiveHint=false, annotations already signal safety, but the description adds valuable behavioral detail: Retry-After on non-terminal states, no result payload, RFC 9457 error shape on failure, and 404 semantics for missing/expired/foreign operations. This goes well 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and mostly front-loads the core behavior, placing the key statement early. However, the opening sentence 'Manage Cloud Analytics reports and get reports data in JSON format' is a generic and somewhat misleading preamble for a status-polling endpoint. That reduces conciseness and clarity.
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 status-polling tool with no output schema, the description is highly complete: it covers all relevant statuses, polling guidance, error behavior, 404 conditions, and redirects to the results endpoint. An agent has enough information to invoke the tool correctly and interpret its response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: customerContext is documented, but operationId only has a type and required flag. The description adds some behavioral meaning to operationId by explaining it identifies an async operation and can be invalid due to tenant mismatch or expiry. However, it does not tell the agent where operationId comes from or clarify the customerContext usage beyond what the schema already states.
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: it returns the current status of an async report operation. It also explicitly distinguishes itself from the results endpoint by stating it does not return result data. The opening sentence about managing Cloud Analytics reports is generic, but the subsequent precision resolves the tool's actual purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: poll async operations using the Retry-After header for pending/running states, and switch to the results endpoint once status is 'succeeded'. It also states what this tool is not for, which is retrieving result data. This clearly routes an agent to the correct sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. Description reinforces 'view details' and notes included content (configuration instructions), adding behavioral context beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no extraneous words. Efficient and clear.
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 low complexity, single parameter with full schema coverage, and annotations present, the description provides sufficient context for correct usage, including when-not and alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter templateId, which has a description. The tool description reiterates the parameter's purpose but adds no new semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details of a specific CloudFlow template by ID, including name, description, and configuration instructions. It distinguishes from sibling tools list_cloudflow_templates and trigger_cloud_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (view specific template by ID) and when not to use (listing all or triggering), with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by specifying exactly what is returned ('insight metadata only') and what is not (individual resources). This is sufficient 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 a single well-structured sentence that front-loads the purpose, then adds usage exclusions. Every part earns its place with no wasted words. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no output schema, the description compensates by listing the return fields (savings, risk counts, status, description). It also clarifies the scope (single insight, no resources). This is complete for the agent to understand what the tool provides and what it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (key and source) with their meanings and examples. Schema description coverage is 100%, so the description does not need to elaborate. The baseline of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns details and aggregate summary of a single optimization insight identified by source and key, explicitly naming the fields (savings, risk counts, status, description). It distinguishes itself from get_insight_resources and list_optimization_recommendations, providing clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'when the user wants the details and aggregate summary of a single optimization insight'. It also provides explicit exclusions: 'does NOT include the individual affected resources (use get_insight_resources for those) and is not for listing all insights (use list_optimization_recommendations)'. This gives clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations which already indicate this is a safe read operation, the description adds that it returns 'full invoice data including line items and status', providing useful behavioral context about the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Every sentence is necessary: first states purpose, second states exclusions and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description mentions what data is returned (line items and status). Combined with annotations and clear usage guidance, it is fully complete for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'id' parameter, so baseline is 3. The description does not add additional meaning about the parameter format or constraints beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('view') and resource ('details of a specific invoice by its ID'), and explicitly distinguishes from siblings by naming alternatives for listing and cost analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('view details of a specific invoice') and when-not-to-use ('do NOT use for listing all invoices or cost analysis') with named alternatives (list_invoices, run_query).
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 declare readOnlyHint=true, destructiveHint=false. Description adds that it returns paginated results with specific fields. No contradictions; description enriches behavioral context without redundancy.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and usage guidance, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately summarizes return content (names, amounts, utilization). Parameters are fully described in schema, no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all parameters are documented in the schema. The description does not add extra parameter-level semantics beyond what the schema provides, meeting the baseline expectation.
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 'Use this when the user wants to see their cloud spending budgets or check budget status' and specifies it returns a paginated list with names, amounts, and utilization. This clearly distinguishes it from siblings like list_alerts and run_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (budgets, status) and when not to (cost analysis -> run_query, alerts -> list_alerts), offering clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying ordering (timestamp descending), included user info, and pagination. 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?
Two focused sentences plus a clear prohibition. Front-loaded with purpose, every sentence provides unique value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description explains return content (activity types, user, ordering) and pagination. Provides sufficient context for a list tool with clear boundaries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context that ss_id and nodeId together identify the node, but does not elaborate on format or constraints beyond what's 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 'change history of a single component node', lists specific activity types (NODE_CREATE/NODE_UPDATE/NODE_DELETE), and distinguishes from siblings like list_cloud_diagram_activity_groups and unrelated tools like run_query or get_cloud_incidents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when the user wants the change history') and when not to use ('Do NOT use for cost analysis or incidents'), with direct alternatives (run_query, get_cloud_incidents). Also describes pagination via offset/limit.
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. Description adds behavioral details: returns a cursor-paginated list with fields (id, name, description, instructions). 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?
Three sentences: purpose/usage, return info, exclusions. No extraneous content; every sentence adds value. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list function, 100% schema coverage, annotations, and sibling list, the description is complete. It specifies return fields despite no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description does not add parameter-specific details beyond what schema provides, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states the tool's purpose: listing the catalogue of CloudFlow templates. It uses specific verb-resource phrasing ('see the catalogue of available CloudFlow templates') and distinguishes from sibling tools like get_cloudflow_template and trigger_cloud_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use ('when the user wants to see the catalogue') and explicit exclusions ('Do NOT use this to view a single template's details...or to trigger a flow'), naming alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. Description adds that it returns a list with metadata, which is useful but not deeply detailed. 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?
Three sentences, front-loaded with purpose, no fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains what is returned (list of folders with metadata). The tool is simple, parameters are covered by schema, and the description provides all needed context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. Description does not add additional meaning beyond what the schema provides, meriting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists Cloud Analytics folders, explains their purpose (organize reports and allocations), and distinguishes from siblings by explicitly saying not to use for reports or labels, naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context ('when the user wants to see their Cloud Analytics folders') and includes 'Do NOT use' guidance with specific sibling tool names (list_reports, list_labels).
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 safety profile is known. The description adds only 'Returns a list of platforms' which is implied by the purpose. No additional behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero wasted words. Front-loaded with purpose, followed by usage guidance. Every sentence serves a clear function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It covers what it does, when to use it, and what not to use it for. No additional information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters and schema coverage is 100%, so the description does not need to add parameter details. The baseline of 4 is appropriate as there is no missing parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available cloud platforms in a DoiT account, using the verb 'see' and resource 'platforms'. It distinguishes itself from sibling tools like get_cloud_incidents and list_products by explicitly saying not to use them for those purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (user wants to see available cloud platforms) and when not to (for cloud incidents or products), naming alternative tools. This provides clear guidance for tool selection.
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 indicate readOnlyHint=false (mutation) and destructiveHint=false (not destructive). The description adds context: ownership constraint ('Only insights owned by the 'public-api' source can be managed'), metadata-only scope, and explicit separation from resource results. It doesn't state error handling or idempotency, but with annotations covering safety profile, 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?
Description is three sentences: first states primary use, second defines ownership and scope, third provides alternative. It's front-loaded with the main purpose. Slightly wordy but every sentence earns its place, providing crucial disambiguation. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters and 5 required, the description covers the key decision points: ownership, metadata vs resources, status alternation. It doesn't detail all params but schema covers them. No output schema exists, but description doesn't promise return format, which is acceptable. The core behaviors are adequately captured 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?
Schema coverage is 100%, so parameters are already well-documented. The description adds specific context by listing the metadata fields (title, description, categories, status, remediation links) and mentions 'remplenishment links' (though not a direct param name, it maps to cloudFlowTemplateId or reportUrl). It reinforces that status can be updated but not solely, adding semantic nuance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the dual purpose: create a new custom insight or update metadata (title, description, categories, status, remediation links). It explicitly identifies the resource and scope (insights owned by 'public-api' source), distinguishing it from sibling tools like post_insight_resource_results and update_insight_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description begins with 'Use this when...' and explicitly states when not to use it: 'Do NOT use this only to change an insight's status (use update_insight_status).' It also distinguishes from post_insight_resource_results for managing affected resources. Provides clear alternatives and exclusions.
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, readOnlyHint:false, openWorldHint:true), the description adds substantial behavioral detail: it highlights the surgical removal, preservation of unlisted tags, and the successful no-op for missing tags. It also discloses namespace mapping behavior for customers. 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 compact yet information-dense, covering purpose, key behaviors, and namespace context in two short paragraphs. It front-loads the main action and avoids redundancy, with every sentence serving 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 mutation tool with no output schema, the description is complete. It addresses the core operation, edge cases (missing tags as no-op), the namespace mapping for customers, and implicitly the difference from add_ticket_tags. It gives enough context for an agent to understand when and how to use it without additional guesswork.
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 covers tags and customerContext with descriptions (67% coverage). The description adds value by explaining the semantic of the tags parameter (surgical removal and namespace mapping) and the customerContext implicit behavior via the namespace. However, it does not fully compensate for ticketId, which is undocumented in both schema and description. The added nuance lifts it slightly above baseline, but high coverage leaves less to add.
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 tool 'Removes one or more tags from an existing support request' with a specific verb and resource. It clearly distinguishes from the sibling tool add_ticket_tags by specifying removal, and clarifies the surgical behavior (only listed tags are removed, others preserved).
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 strongly implies usage for removing tags and explains the no-op behavior for absent tags, which helps avoid misuse. It also contrasts with the add operation via namespace mapping, showing awareness of the sibling. However, it does not explicitly state when NOT to use it (e.g., for adding tags) or name alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. Description adds the confirmation requirement and the sentinel 'default' behavior, enhancing 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?
Three focused sentences: purpose, parameter explanation, usage directive, and exclusion. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, parameter details, usage context, and exclusions from siblings. Completely adequate for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage for the single parameter themeId, with a detailed description. Description reinforces the sentinel concept but adds no new semantic information 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?
Clearly states the tool changes/activates a custom color theme for Cloud Analytics reports. Explicitly distinguishes from siblings get_active_theme and update_theme, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (user wants to change/activate theme) and when not to (retrieving or updating). Directs to ask user for confirmation, covering both context and best practice.
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`, `openWorldHint: true`, and `destructiveHint: true`, which signal mutation and potential destruction. The description goes beyond annotations by detailing the merge-patch behavior (omitted or null leaves unchanged, with exception for `urlSlug`), permission requirements, and the restriction that `currency` cannot be cleared. It does not mention rate limits or idempotency, but the provided context is substantial. 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 dense but well-structured: first paragraph sets the purpose and permissions, second explains the merge-patch semantics with edge cases, and third ties to `getCustomer` structure and specific field behaviors. It is front-loaded with the core action and prerequisites. Some redundancy with the schema descriptions exists (e.g., field nesting information), but the additional clarity justifies the 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?
Given the tool's complexity (nested objects, permissions, merge-patch behavior, clearing semantics), the description is thorough. It lacks an output schema so it doesn't explicitly describe return values, but the description focuses on the request side. It covers key edge cases (urlSlug clearing, currency non-clearable, permissions) and references `getCustomer` for symmetry, making it complete enough for agents 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?
Schema coverage is 80% and the schema includes detailed descriptions for most parameters (e.g., `urlSlug` constraints, `mfaRequired` behavior, `allowedInviteDomains` permissions). The description adds meaningful context beyond the schema by explaining the merge-patch semantics, clearing behavior, and nested structure consistency with `getCustomer`. It also clarifies the `customerContext` parameter's role for DoiT employees. Given the high schema coverage, the description mostly reinforces and boosts clarity, but not all parameters (e.g., `contact.emails` detailed constraints) are fully elaborated in the description itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool reads and updates general settings, and precisely describes the partial update semantics for the customer identified by `{customerId}`. It explicitly names the resource (customer) and the operation (partially update), and ties it to the sibling `getCustomer` tool, distinguishing it as the write counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it's for updating settings/contact info of the customer matching the bearer token. It states when it must NOT be used (different customer yields 403), requires the `Settings` permission and external API access, and notes the extra `UsersManager` permission for `allowedInviteDomains`. It also explains the merge-patch semantics and how to clear fields, which is essential for correct usage.
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 key behaviors: tag normalization (trim + lowercase), prefixing with 'customer_tag/' for customer-submitted tags, no-op on duplicate tags, and response echoing actual stored strings. These details go beyond the annotations and give a clear expectation of 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 concise and well-organized in two paragraphs. The first sentence ('Create and manage support tickets with DoiT.') is generic and somewhat redundant, but the rest is focused and efficient. No 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?
The description covers the operation's side effects, normalization, and idempotency, and mentions the response echoes stored strings. It does not discuss error conditions or authorization requirements, but for a mutating tag-add operation, the provided context is sufficient for an agent to understand the tool's function.
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 adds significant meaning to the tags parameter by explaining normalization, prefixing, and the no-op behavior. It also clarifies that ticketId refers to an existing support request, supplementing the schema's minimal description and complementing the customerContext parameter's schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: adding one or more tags to an existing support request. It explicitly mentions that the operation is surgical and preserves existing tags, distinguishing it from broader ticket update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/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 (when adding tags without affecting other ticket fields) but does not explicitly compare it to alternatives like update_ticket or remove_ticket_tags. The mention of 'surgical' and 'no-op on re-add' provides behavioral context but lacks explicit usage 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 indicate readOnlyHint=false and destructiveHint=true. The description adds behavioral context: the tool is for creation, requires confirmation, and that it connects an account for automation. It does not detail potential side effects (e.g., costs), but provides useful beyond-annotation guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, concise, and front-loaded with the core purpose. Every sentence adds essential information 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?
Given the tool's complexity (nested objects, no output schema), the description covers purpose, usage constraints, and confirmation needs. It does not explain return values or error scenarios, but for a create tool with clear sibling differentiation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by emphasizing the mutual exclusivity of gcpConfig and awsConfig and the need for user confirmation. It does not repeat parameter schemas but adds contextual usage hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new CloudFlow cloud provider connection (GCP or AWS). It uses a specific verb ('create') and resource ('CloudFlow connection'), and distinguishes from sibling tools like update_cloudflow_connection and trigger_cloud_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this when the user wants to create...' and provides when-not-to-use guidance (do not use for updates or triggering). It also specifies the constraint that exactly one of gcpConfig or awsConfig must be supplied, and advises confirming with the user before executing.
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 indicate destructiveHint=true, so the description's mention of 'save' aligns. It adds the behavioral note to confirm parameters before execution. No contradictions, but could disclose more about side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words. Front-loaded with core purpose and usage guidance. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the config object and no output schema, the description provides sufficient context: when to use, how to use (confirm, use dimension tool), and exclusion cases. Could elaborate on return value but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by referencing the dimension tool for valid IDs and advising parameter confirmation, which aids correct usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for saving a new Cloud Analytics report with a specific configuration, using the verb 'save' and specifying the resource. It also distinguishes from run_query for one-time queries, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (user wants to save a new report) and when not to use (one-time queries, directing to run_query). Also advises to ask user to confirm parameters, providing clear usage 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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by revealing that the tool returns 'current utilization' and accepts partial case-insensitive name matching. It does not contradict annotations. A 4 is given because it adds meaningful context without needing to reiterate 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 sentences, front-loaded with the primary use case, followed by alternative tool exclusions. Every sentence adds value, no redundancy. It is structured for quick scanning 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?
Given the tool has only two simple parameters, no output schema, and annotations covering safety, the description provides sufficient context. It explains parameter behavior and differentiates from related tools. Minor gap: does not describe the return format, but that is acceptable without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema coverage at 100%, baseline is 3. The description adds value by explaining that 'name' is for partial case-insensitive matching when ID is unknown, and 'id' for direct retrieval. This clarifies parameter usage beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: viewing details and current utilization of a specific budget. It specifies the action ('view'), resource ('budget'), and inputs (ID or partial name). It distinguishes itself from siblings by explicitly mentioning when not to use it (list_budgets, run_query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'when the user wants to view the details and current utilization of a specific budget.' It also gives alternatives for related tasks: list_budgets for listing all budgets, run_query for cost analysis. This clearly sets usage boundaries.
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 openWorldHint=true. Description adds that it returns diagrams with connected layers and optionally components, and that it is a discovery endpoint. Does not disclose rate limits or auth, but annotations cover safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, tightly organized. Each sentence serves a purpose: usage context, output summary, primary discovery hint, parameter filtering options, and exclusions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description states return value: diagrams with connected layers and optionally components. Given the tool's discovery role and many siblings, this is sufficient. Could mention potential volume or pagination, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds practical context: explains when to set include_components=true (to get component IDs for other endpoints) and mentions skip_empty defaults to false. This adds value beyond 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 tool discovers all cloud infrastructure diagrams and their layers, and retrieves layer IDs. It explicitly distinguishes from sibling tools like run_query and search_cloud_diagrams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: uses it as primary discovery before endpoints needing layer ID, and explicitly says NOT to use for cost analysis (use run_query) or diagram search (use search_cloud_diagrams).
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, so read-only behavior is covered. The description adds value by explaining the matching behavior (accepts ID or partial title, case-insensitive), but does not address edge cases like when both parameters 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 three concise sentences, front-loaded with purpose, then matching logic, then exclusions. Every sentence is necessary 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?
Given the low complexity (two optional params, no output schema, clear annotations), the description covers purpose, usage, matching behavior, and sibling differentiation adequately, though it could mention what happens if both id and title are provided.
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 cover both parameters (100% coverage), and the description adds semantic context: parameters are alternatives, and title match is case-insensitive partial. This goes 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 states 'view details of a specific cloud platform incident' with a clear verb and resource, and explicitly distinguishes from sibling tools like get_cloud_incidents and get_anomalies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (user wants details of a specific incident) and when not to use (listing all incidents or anomalies), with alternative tool names 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, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context by specifying the exact data the tool returns. No contradictions. Could mention data freshness or limits but not necessary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. It front-loads the purpose and provides clear usage guidance immediately.
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 no-parameter dashboard tool, the description lists all key return fields. No output schema exists, but the text compensates. Minor missing detail: data freshness or pagination, but acceptable for a high-level overview.
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?
No parameters exist, schema coverage is 100%. With no parameters, the baseline is 4. The description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a high-level overview or dashboard of entire cloud infrastructure, listing specific data points (cost, top services, projects, anomalies, incidents). It distinguishes itself from siblings like run_query and get_anomalies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use (high-level overview) and when not to (detailed drill-downs, single-provider analysis, anomaly-only queries), and provides an alternative tool (run_query).
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 read-only; description adds that values are customer-specific and filter-oriented. 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?
Three sentences: main purpose, example, negation. No fluff, 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 lookup tool, purpose, usage, and exclusions are well covered. Missing explicit return format, but not critical given purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both params with descriptions; description adds an example mapping type and id to realistic values, slightly enhancing meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'look up valid filter values' for a specific dimension and distinguishes from siblings list_dimensions and run_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (before run_query, view dimension details) and when not (list_dimensions, run_query), with a concrete example.
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=true and destructiveHint=false. The description adds specifics on what the tool returns (resource IDs, accounts, savings, remediation details), providing additional 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?
Two concise sentences, front-loaded with purpose, no unnecessary words. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description adequately explains the return data (resource IDs, accounts, savings, remediation). It doesn't discuss pagination or limits, but for a focused read-only tool, it is sufficiently 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?
Input schema has 100% coverage with descriptions. The description adds extra guidance by referencing the source and key fields from list_optimization_recommendations, linking to another tool's output for clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns specific resources affected by an optimization insight, including resource IDs, accounts, savings, and remediation details. It distinguishes from listing all insights by explicitly saying not to use it for that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when the user wants to see which specific resources are affected' and 'Do NOT use this for listing all insights (use list_insights)', providing clear guidance and an alternative 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 indicate readOnly and non-destructive; description adds that it accepts ID or partial name (case-insensitive). Provides useful context beyond 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?
Two sentences: first sentence states purpose, second adds negative guidance. No redundant wording. Front-loaded with key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage boundaries, and parameter semantics. For a simple retrieval tool with no output schema, it is adequately complete—though it could mention return format or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description reinforces that name is a partial case-insensitive match and clarifies that either ID or name can be used (not both). Adds value over 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?
Clearly states the verb 'retrieve' and resource 'data results of a specific saved report'. Explicitly distinguishes from sibling tools by stating what it is not for (list_reports, run_query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when to use (retrieve data results) and when not to use (listing reports or running ad-hoc queries). References specific alternative tools by 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 mark it read-only non-destructive. Description adds return structure (grouped by snapshot, ordered by timestamp, details about individual activity records), pagination, and filtering. Provides good additional 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?
Three sentences: first gives main usage and return structure, second details ordering and grouping, third provides exclusions. Front-loaded and 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?
With 4 parameters (all described) and no output schema, the description explains the return structure, ordering, and grouping. It covers pagination and filtering. Missing some specifics about activity record fields, but overall sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds functional context: 'Page with offset/limit and filter with tags,' grouping the parameters into usage patterns. This adds value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists change history of a cloud diagram layer grouped by snapshot. It specifies the resource ('activity groups') and distinguishes from siblings by explicitly excluding cost analysis and incidents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when the user wants the change history...' and provides clear exclusions with alternative tools: 'Do NOT use this for cost analysis (use run_query) or incidents (use get_cloud_incidents).'
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: returns a cursor-paginated list with config and status. No contradiction, and it enriches the agent's understanding 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?
Three sentences, front-loaded with purpose, no superfluous information. Every sentence adds value and fits within the typical brevity expected of MCP descriptions.
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 list tool with good annotations and full schema coverage, the description sufficiently explains the return type (list with config and status) and pagination. Minor omission: no mention of error behavior or rate limits, but overall 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (pageToken, maxResults) described in the schema. The description adds no additional semantic detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pair ('see their CloudFlow cloud provider connections') and immediately distinguishes itself from sibling tools by stating what not to use it for (triggering a flow or viewing a single connection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when the user wants to see their CloudFlow cloud provider connections') and provides clear exclusions and alternatives: 'Do NOT use this to trigger a flow (use trigger_cloud_flow) or to view a single connection's details (use get_cloudflow_connection).'
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=true and destructiveHint=false, so the description adds minimal behavioral context. It does state the return type (list of datasets with metadata), which is helpful. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff, front-loaded with purpose and usage guidelines. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the essential purpose and exclusions. It could be slightly more complete by mentioning pagination or scope, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are defined, so schema coverage is 100%. The description does not need to add parameter semantics, and it does not. Baseline 4 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 uses a specific verb (list) and resource (DataHub datasets), clearly stating it returns a list with metadata. It also distinguishes itself from siblings by explicitly noting what it does not cover (billing data and assets).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('when the user wants to see available DataHub datasets') and when not to use ('Do NOT use this for billing data or assets'), providing alternative tool names (run_query, list_assets).
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, indicating a safe read operation. The description adds context about defaulting behavior, row limits, and the need to call get_dimension for filter values, enhancing 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with paragraphs, bullet points, and an example. Information is front-loaded with purpose and usage. However, it is verbose in places, repeating some advice (e.g., group defaults mentioned twice). Still, every section 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 complex tool with many nested parameters and no output schema, the description covers use cases, defaults, pitfalls, and provides a comprehensive example. It could briefly mention the response format, but overall it equips the agent with sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description adds significant value by explaining field usage (e.g., includeCurrent meaning, group defaults, filter value requirements). It warns about deprecated metric fields and provides examples that clarify nested structures.
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: to analyze cloud costs, generate cost breakdowns, and run custom analytics queries. It explicitly distinguishes from siblings by listing when not to use it (list_reports, get_anomalies, list_budgets), making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (cost analysis, trends) and when-not-to-use scenarios (listing reports, checking anomalies, budgets). Offers detailed guidance on default values, field precedence (timeRange over customTimeRange), and required group defaults, with concrete examples.
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?
Annotations indicate destructive and open world, and the description adds 'executes automation that may modify cloud resources externally', providing additional 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?
Three concise sentences: first states purpose, second adds behavioral info, third gives negative guidance. Front-loaded and efficient with no 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 tool with 2 parameters (one optional object) and no output schema, the description covers purpose, usage boundaries, and behavioral traits. Missing details on return format or error handling, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description mentions 'flow ID' and 'any parameters' but adds minimal extra meaning beyond the schema definitions for flowID and requestBodyJson.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool triggers a CloudFlow workflow by flow ID, distinguishing from viewing definitions or checking available flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (to trigger a flow) and when not to use (not for viewing definitions or checking available flows), and advises asking the user to confirm the flow ID and parameters before executing.
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 adds behavioral insight beyond annotations: it instructs to ask for user confirmation before executing changes, which is important for a destructive operation (destructiveHint=true). It does not contradict any 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 consists of three concise sentences, front-loading the main purpose, then adding guidance and exclusions. No 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?
Given the tool has 5 parameters and no output schema, the description covers purpose, usage, and behavior well. However, it lacks information about what the tool returns, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 5 parameters. The tool description does not add additional meaning or context beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies existing annotations, with specific verb 'modify' and resource 'existing annotation'. It also distinguishes from siblings by explicitly saying not to use for creating annotations (use create_annotation) or labels (use update_label).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('user wants to modify an existing annotation'), when-not-to-use (creating annotations or labels), and advises to ask user for confirmation before executing. This is comprehensive.
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 dismissal can include a reason and comment, and emphasizes the source restriction. It does not elaborate on side effects or error behavior, but given the annotations cover the safety profile, the additional context is sufficient. 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?
Three sentences that are front-loaded with the primary usage, followed by constraints and exclusions. Every sentence provides essential information without redundancy. Very concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested object and enumerated statuses, but no output schema. The description covers the main intent, constraints, and usage context sufficiently for an agent to select and invoke it correctly. It could mention what happens after a successful update (e.g., confirmation or return value), but that is not critical given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already described. The description adds value by linking dismissalDetails to the 'dismissed' status and clarifying that source is fixed to 'public-api' beyond the schema's default. It also reiterates valid statuses in a practical way, helping the agent understand usage context.
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 ('change') and resource ('display status of an existing insight'), and immediately distinguishes it from sibling tools by explicitly excluding editing title/description and creating (post_insight_result). It also names specific status values, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use ('when the user wants to change the display status') and when-not-to-use ('Do NOT use this to edit an insight's title/description or create one'), naming the alternative tool (post_insight_result). It also adds a constraint about source ownership, giving clear context for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses partial updates and confirmation requirement, aligning with destructiveHint=true. Does not contradict annotations and adds useful 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?
Very concise: three short sentences with no unnecessary words. Front-loaded with purpose and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, partial updates, confirmation, and sibling distinction. Lacks details on return behavior, but no output schema exists. Adequate for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, so description adds minimal value. However, mentions using 'dimension tool' for valid IDs, which is a helpful hint beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'modify an existing saved Cloud Analytics report' with a specific verb and resource. Differentiates from run_query for ad-hoc queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (modify existing report) and when not (ad-hoc queries, referencing sibling run_query). Also instructs to ask user for confirmation.
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 readOnlyHint=false. The description adds behavioral context by advising agent to confirm changes before executing, which enhances 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?
Three concise sentences: first gives purpose and actions, second provides usage context, third excludes sibling tools. No unnecessary words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (5 params, nested objects, no output schema), the description covers what the tool does, how to identify the theme, what can be updated, and usage restrictions. Missing return value description but acceptable without output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that id and name are alternative identification methods (partial name match), which is not obvious from individual property 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 'modify an existing custom color theme' with specific actions (rename, change primary color, update palette). It also distinguishes from siblings by explicitly saying not to use for creating or switching themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (modify existing theme) and when-not-to-use (creating new theme, changing active theme, which is handled by set_active_theme). Also instructs to ask user for confirmation, guiding safe invocation.
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. Description adds useful context about sentinel 'default' value and return type. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with usage condition, no wasted words. Perfectly concise.
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?
Fully explains purpose, usage, and return value. No missing context considering zero parameters and simple behavior.
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?
No parameters, schema coverage 100%. Description correctly implies no inputs needed. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns the active theme id for user's account, and explains the sentinel 'default'. Distinguishes from siblings by explicitly saying not to use for listing themes or fetching a specific theme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (user wants active theme) and when not to use (list_themes, get_theme), naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, indicating a safe read operation. The description adds behavioral context: accepts partial name (case-insensitive) and warns against misuse, but doesn't 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?
Three sentences, no fluff. Front-loaded with core purpose, then acceptance criteria, then exclusions. Every sentence is essential.
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 no output schema and low complexity, the description is complete. It specifies inputs (ID or name), explains how they work (partial/case-insensitive), and clarifies scope (specific alert only, not list).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, with descriptions for both parameters. The description adds that the 'name' parameter is a 'partial name match (case-insensitive)' and explains it is used 'when ID is unknown', providing context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'view the details of a specific cost alert'. It distinguishes from sibling tools by explicitly saying not to use for listing all alerts (list_alerts) or for anomalies (get_anomalies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use ('when the user wants to view the details of a specific cost alert') and when-not-to-use ('Do NOT use this for listing all alerts... or anomalies'). It also references specific sibling tools as alternatives.
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?
Annotations already indicate readOnlyHint=true. Description adds that it accepts ID or partial name (case-insensitive), providing 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?
Two sentences, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with clear annotations and schema, the description is complete and provides all necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds minor context (one of the two parameters needed, partial name is case-insensitive) but doesn't significantly enrich 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 the verb 'view details' and resource 'specific cost allocation', and distinguishes from siblings like list_allocations and run_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly explains when to use (view specific allocation) and when not to (listing, queries), naming alternative 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?
Goes well beyond the sparse annotations: create-only semantics, no publishing or schedule activation, incomplete-flag behavior for unbound connections/tables, auto-creation of global variables, table creation limited to structure, and dry-run with no writes. This gives an agent a precise behavioral model.
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 core behavior and each additional sentence covers a distinct high-value aspect: restrictions, binding/requirement handling, table creation options, and dry-run validation. The length is justified by the tool's complexity with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex nested bundle importer with no output schema, the description covers the main behavioral contracts, failure/validation modes, and response shape for dry-runs. It also explains tenant-scoped requirements and what happens to unbound resources, so a caller can safely attempt an import.
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 coverage at 50%, the description compensates by explaining bindings semantics (requirement key → target resource ID), the createMissingTables behavior, and dry-run's parameter effect. It does not mention every parameter, but the ones with non-obvious semantics are addressed meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation: 'Creates every flow of a previously exported bundle in the authenticated tenant.' It clarifies that imports are create-only with new IDs, which distinguishes it from read/list/export CloudFlow siblings without needing to inspect schemas.
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 explains when to use the tool (importing a previously exported bundle) and instructs to run with ?dryRun=true first to validate and discover required bindings. It does not explicitly name sibling alternatives or state when not to use it, but the context is 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 declare readOnlyHint, openWorldHint, destructiveHint, so the description's safety profile is covered. The description adds behavioral transparency by detailing the return content (fields), which annotations don't cover. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first provides usage context, second describes return. No unnecessary words. Front-loaded with 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?
Given no parameters and no output schema, the description is complete. It covers when to use, what it returns, and exclusions. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline for 0 parameters is 4. The description does not need to explain parameters, but it correctly implies no input needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing the DoiT account team/account managers for the user. It specifies the returned fields (name, email, role, Calendly link) and distinguishes from siblings (list_users, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use ('Use this when the user wants to know who their DoiT account team / account managers are') and when not to use ('Do NOT use this for listing platform users (use list_users) or organizations (use list_organizations)'). Provides clear alternatives.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond them: newest-first ordering, default inclusion of test runs, pagination semantics including the stop condition, and an explicit statement of what is NOT returned (per-node detail). This is richer behavioral disclosure than most sibling definitions provide.
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 longer than average but nearly every sentence earns its place: ordering, mode default, sibling routing, and pagination instructions are all load-bearing. The only waste is the vague opener 'Manage CloudFlow,' which repeats the tool's domain without adding decision-relevant information. Front-loading the core result before the pagination details is good structure.
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 5-parameter paginated list tool with no output schema, the description covers the critical operational details: what is returned, ordering, default mode, pagination chaining, and where to go for deeper detail. Gaps remain: the shape of a run object is never described (though no output schema exists), and maxResults behavior (default page size) is not clarified. The pagination stop-condition guidance is the kind of completeness that prevents agent loops.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 20% (only customerContext documented), so the description carries a high burden. It explains mode ('separate test runs from production ones — test runs are included by default') and pageToken ('passing the response's pageToken value as the pageToken parameter'), which are the two behaviorally meaningful parameters. However, maxResults is never mentioned despite being undocumented in the schema — the agent must infer its role purely from the schema min/max.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Returns a flow's runs, newest first.' It also explicitly distinguishes itself from the single-run sibling by noting 'Per-node detail is not included here; fetch a single run...' — an agent can tell this tool apart from get_cloudflow_flow_run and list_cloudflows without opening their schemas. The opening 'Manage CloudFlow' is filler, but the substantive content is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative and the condition that selects it: 'Per-node detail is not included here; fetch a single run to read what each node consumed and produced.' It also gives concrete usage guidance for pagination ('call again passing the response's pageToken value... Stop once the response has no pageToken') and for the mode parameter ('test runs are included by default'). Nothing is left to inference.
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 that it returns a list of roles with permissions, which is useful behavioral context beyond the annotations. However, it doesn't elaborate on other behaviors like pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the usage directive, and has no wasted words. Every sentence is valuable.
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 zero parameters, no output schema, and comprehensive annotations, the description is complete enough. It covers the purpose, usage guidelines, and return value adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%. Per the guidelines, baseline is 4 for no parameters, and the description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists roles in a DoiT organization and returns permissions. It uses a specific verb and resource, and distinguishes from siblings like list_users and 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use (viewing roles) and when not to use, providing alternative tools (list_users, list_organizations). This gives clear 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. Description adds that it returns a list of themes with metadata and explains what themes do (control report colors), which is useful 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?
Three concise sentences: usage context, return value, and what not to use. No redundant wording.
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?
Completely describes the tool's purpose and output for a simple zero-parameter listing tool. No output schema needed given simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has 0 parameters and 100% schema coverage, so baseline is 4. Description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists custom color themes for Cloud Analytics reports, with explicit verb 'list' and resource 'themes'. Differentiates from siblings by name-dropping list_reports and list_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use ('when the user wants to see custom color themes') and when not to use (for reports or labels), with alternative tool names 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 cover read-only and non-destructive nature. Description adds that it returns a list with roles, which 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?
Three sentences that are direct and front-loaded. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, good annotations, and a clear purpose with usage guidance, the description is 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description doesn't need parameter details. Baseline 4 applies as there is nothing missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns a list of users with roles in the organization, and distinguishes from sibling tools like list_roles and validate_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (user wants to see users) and when not (for roles or validating current user), with named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) are consistent with the read-only search behavior. Description adds that it returns scheme, components, and prop matches, and supports optional scoping. Does not disclose pagination behavior or result limitations, but annotations already convey safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: first states main use, second describes returns and optional scope, third provides negative guidance. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with full schema coverage and safety annotations, this description covers purpose, return types, scoping options, and exclusions. No output schema needed since return is described textually. Sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100% coverage). Description adds context by explaining what from/size do for pagination per category and that ss_id limits to a layer. It also states the search returns three categories, enhancing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'search their cloud infrastructure diagrams and components by name or property', specifying verb, resource, and scope. It distinguishes from siblings by naming alternatives for cost analysis (run_query) and incidents (get_cloud_incidents).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (search by name/property) and when not to use (cost analysis or incidents), with exact tool names. Also mentions optional scoping parameters (ss_id, from/size) for narrowing search.
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, it discloses substantial behavioral details: execution is identical to production, approval-gated nodes still wait for real approval, the run is recorded as a test, it does not affect history/dashboards/budgets, it holds the concurrency lock causing 409s, and validation failures return 422 listing all offending nodes. This gives an agent a clear model of side effects and failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every paragraph earns its place: sibling distinction, execution semantics, side effects, concurrency behavior, validation behavior, and error handling. Key differentiators are front-loaded in the first two sentences, and the rest is structured by topic.
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 complex tool with no output schema, the description covers the full lifecycle: when to use, preconditions, execution semantics, side effects, concurrency conflicts, validation errors, how to follow the run via Location URL, and the dryRun escape hatch. An agent has enough context to invoke it correctly and interpret meaningful outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics for dryRun ('validate the flow without starting a run'), which is useful given low schema coverage. However, flowId and Idempotency-Key receive no explicit explanation beyond their names and required status, and customerContext is left to the schema's own description. The description only partially compensates for the low schema_description_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 a specific action (runs a flow once as a test) and a specific resource (CloudFlow), while immediately distinguishing itself from the alternative that requires a published flow. This clearly separates it from trigger_cloud_flow even though the description refers to it by the older name 'actions/trigger'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this tool to verify a newly authored or edited flow before publishing, and contrasts it with the tool that requires a published flow. It also gives one additional usage condition: the first node must be webhook, scheduled, or manual trigger, and describes the dryRun alternative for validation without execution.
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 destructiveHint=true, but description adds transparency by specifying that only the description can be changed and that a required confirmation step is needed. 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?
Four sentences with clear front-loading of purpose. Every sentence adds value: usage context, required parameter, change scope, confirmation step, and exclusions with alternatives. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation (update a single field) and no output schema, the description covers all necessary context: what the tool does, required parameter, change limits, and safety instruction. Annotations complement the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds meaning by reinforcing that the name parameter is only for identification and cannot be changed, and that description is the only updatable field. This provides context beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (modify/update), resource (DataHub dataset), and scope (description only). It distinguishes from sibling tools by explicitly mentioning not to use for creating or listing, with alternative tool names provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (modify an existing dataset's description) and when not to use (creating or listing), naming alternative tools. Also instructs to ask for user confirmation before executing.
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 that the OAuth token ensures authentication, precluding proactive calls. However, it does not detail what information the tool returns, which would be helpful given no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with critical usage rules, no superfluous words. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and clear annotations, the description fully informs the agent about when to invoke. It covers the tool's role in the authentication flow.
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 zero parameters, schema coverage is 100%, and the description implicitly confirms no arguments needed. Baseline 4 is appropriate as no additional param info required.
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: 'verify their account connection or check who they are logged in as'. It also distinguishes from sibling tool 'list_users'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use instructions, including an alternative tool reference. 'Do NOT call this proactively... Do NOT use this for listing users in the organization (use list_users).'
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?
Annotations already declare the tool as read-only and non-destructive. The description adds behavioral context beyond annotations, such as accepting a partial name (case-insensitive) and returning details. 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 concise (two sentences) and front-loaded with the purpose. Every sentence adds value without redundancy. It efficiently communicates the core functionality and constraints.
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, no output schema, and comprehensive annotations, the description provides sufficient context. It covers what the tool does, how to use parameters, and when to avoid it. A slight gap is the lack of detail on what 'details' are returned, but this is acceptable for a well-understood domain.
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 fully describes both parameters (id and name), but the description adds meaning by explaining that 'name' supports partial match and case-insensitive lookup, and that 'id' is the theme ID. This clarifies the exact usage beyond the schema's generic 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 explicitly states the tool's purpose: 'view details of a specific custom color theme'. It identifies the resource (custom color theme) and action (view details). Additionally, it distinguishes from the sibling tool 'list_themes' by specifying when not to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool ('when the user wants to view details of a specific custom color theme') and when not to use it ('Do NOT use this for listing all themes (use list_themes)'). This helps the agent select the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the description doesn't need to reiterate. It adds context by stating it updates sharing settings and sets per-user roles or public visibility. It doesn't explicitly state that existing permissions are replaced, but 'set' implies it. Overall, good 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?
Three sentences that are front-loaded: first sentence gives usage context, second explains action and scope, third adds requirements and exclusion. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently covers input requirements, action, and when not to use. It provides all necessary context for an agent to correctly 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?
Schema coverage is 100%, but the description adds value by noting the condition that at least one of permissions or public must be provided, which is not in the schema. It also clarifies the public option's effect (share with all users or make private). This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates sharing settings (per-user roles and/or public visibility) for specific resource types (alert, budget, report, allocation). It explicitly distinguishes from get_resource_permissions, ensuring no confusion with a read sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies when to use: when changing sharing or access levels. It also explicitly says when not to use: for viewing permissions, directing to get_resource_permissions. It lists requirements (resourceType, resourceId, at least one of permissions or public).
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?
Annotations indicate destructiveHint=true, and the description confirms mutability by listing modifications. It adds the behavioral detail 'ask the user to confirm the changes before executing,' which aligns with the destructive nature. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, and each sentence adds value without redundancy. Highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (1 required), no output schema, and sufficient annotations, the description covers what the tool does, constraints, and usage guidance. It also includes a recommendation to confirm, making it complete for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds value by summarizing constraints ('All fields except connectionId are optional; at most one of gcpConfig or awsConfig') beyond the schema, though the schema already provides detailed explanations.
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 CloudFlow cloud provider connection' and lists specific updatable fields (rename, description, enable/disable, GCP/AWS config, collaborators). It explicitly distinguishes from create_cloudflow_connection and trigger_cloud_flow, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (update existing connection) and when not to use (not for create or trigger). Also instructs to ask user for confirmation before executing, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, openWorldHint=true, destructiveHint=true, which the description fully supports. Beyond that, it discloses the server-side resolution of the assignee to a Zendesk agent, the 400 error for unresolvable emails, the Zendesk auto-close behavior, and that the response echoes applied fields. This far exceeds what the annotations alone convey and adds genuine behavioral context. 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 a single dense paragraph of roughly 120 words. Every sentence carries load-bearing information (permissions, exclusions, error behavior, response format), so nothing is wasted. It's somewhat long, but the volume is justified by the role-based permission model and Zendesk integration details. Slightly compact structure but front-loaded with the core 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?
With no output schema, the description properly explains the return value ('The response echoes the fields that were applied'). It covers the permission model, error cases (400 for unresolvable assignee), enum constraints, auto-close behavior, and the requirement that at least one mutable field be present. For a moderate-complexity mutation tool touching Zendesk, this is fully complete.
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 75% (only `ticketId` lacks a schema description, and it's a simple number). The description adds substantial meaning: `status` semantics are role-restricted with an enum, `assignee` is contextualized as a DoiT-employee email resolved server-side, and `customerContext` explains when it's required vs omitted. This adds deep semantics beyond the bare schema text.
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 the generic framing 'Create and manage support tickets' but then states a precise purpose: 'Partially updates a support request' with the specific fields involved (`status`, `assignee`). It clearly distinguishes from the sibling `create_ticket` and aligns with other ticket tools. The verb+resource+scope is 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage rules are exceptionally explicit: DoiT employees may set `open`/`pending`/`hold`/`solved` and the assignee, while customers may only set `solved` and may not set an assignee. It explicitly states what is NOT possible (`closed` is not settable via API, auto-closed from `solved`) and the constraint 'At least one mutable field must be present.' This is concrete when/when-not guidance, though it doesn't name alternative tools.
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:

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

Score Badge

Copy to your README.md:

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

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